MVC Structure - Yoneily

Overview

Sistema Magdaleno follows the CakePHP 1.3 MVC (Model-View-Controller) architecture pattern. The application is organized into distinct layers that separate business logic, data access, and presentation concerns.

Directory Structure

sistema_magdaleno/
├── app/
│   ├── config/              # Configuration files
│   ├── controllers/         # Controller classes
│   │   ├── components/     # Reusable controller logic
│   │   └── *_controller.php
│   ├── models/             # Model classes
│   │   ├── behaviors/      # Reusable model logic
│   │   └── datasources/    # Custom data sources
│   ├── views/              # View templates
│   │   ├── elements/       # Reusable view fragments
│   │   ├── helpers/        # View helper classes
│   │   ├── layouts/        # Page layouts
│   │   └── {controller}/   # Controller-specific views
│   ├── webroot/            # Publicly accessible files
│   │   ├── css/
│   │   ├── js/
│   │   ├── img/
│   │   └── files/          # Uploaded files
│   ├── tmp/                # Temporary files & cache
│   ├── vendors/            # Third-party libraries
│   ├── plugins/            # CakePHP plugins
│   ├── locale/             # Internationalization files
│   ├── tests/              # Unit tests
│   ├── app_controller.php  # Base controller
│   └── index.php           # Application entry point
├── cake/                   # CakePHP core framework
├── plugins/                # Global plugins
├── vendors/                # Global vendor libraries
└── index.php               # Root entry point

Controllers

Location

app/controllers/

Available Controllers

Controller	Purpose
`denuncias_controller.php`	Complaint/report management
`galleries_controller.php`	Image gallery CRUD operations
`groups_controller.php`	User group & permission management
`locales_controller.php`	Business location management
`pages_controller.php`	Static page handling
`promos_controller.php`	Promotional content management
`registers_controller.php`	User registration & campaigns
`users_controller.php`	User authentication & profile management
`ventas_controller.php`	Sales/transaction handling
`videos_controller.php`	Video content management

Base Controller (AppController)

File: app/app_controller.php All controllers extend AppController, which provides shared functionality:

class AppController extends Controller {
    var $components = array(
        'Acl',           // Access Control Lists
        'Auth',          // Authentication
        'Session',       // Session management
        'Email',         // Email sending
        'PasswordHelper' // Password utilities
    );
}

Key Methods

beforeFilter() Executes before every controller action:

function beforeFilter() {
    parent::beforeFilter();
    
    // Configure authentication
    $this->Auth->loginAction = array(
        'controller' => 'users', 
        'action' => 'login'
    );
    
    // Allow public access to specific actions
    $this->Auth->allow('add_vendedor', 'consulta_codigo', 'registrado', 'display');
    
    // Set redirect after login
    $this->Auth->loginRedirect = array(
        'controller' => 'users', 
        'action' => 'home'
    );
    
    // Enable controller-based authorization
    $this->Auth->authorize = 'controller';
}

isAuthorized() Authorization callback (returns true to allow access):

function isAuthorized() {
    return true; // Delegates to ACL system
}

build_acl() Automatically builds ACL tree from controllers/actions (debug mode only):

Scans all controllers in app/controllers/
Creates ACO nodes for each controller
Creates ACO nodes for each public action
Supports plugin controllers

Controller Naming Convention

File: {plural_name}_controller.php (e.g., users_controller.php)
Class: {PluralName}Controller (e.g., UsersController)
Extends: AppController

class GalleriesController extends AppController {
    var $name = 'Galleries';
    // ...
}

Models

Location

app/models/

Available Models

Model	Database Table	Purpose
`User`	`users`	User accounts
`Group`	`groups`	User groups
`Gallery`	`galleries`	Image galleries
`Archivo`	`archivos`	Uploaded files
`Video`	`videos`	Video content
`Category`	`categories`	Content categories
`Locale`	(locales table)	Business locations
`Campana`	`campanas`	Marketing campaigns
`Register`	`registers`	User registrations
`Denuncia`	(denuncias table)	Complaints/reports
`Aco`	`acos`	ACL objects
`Aro`	`aros`	ACL requesters
`ArosAco`	`aros_acos`	ACL permissions junction

Model Naming Convention

File: {singular_name}.php (e.g., user.php)
Class: {SingularName} (e.g., User)
Extends: AppModel
Table: {plural_name} (e.g., users)

class Gallery extends AppModel {
    var $name = 'Gallery';
    var $primaryKey = 'id_galeria'; // Custom PK
}

Model Associations

belongsTo

var $belongsTo = array(
    'User' => array(
        'className' => 'User',
        'foreignKey' => 'usuario_id_usuario'
    )
);

hasMany

var $hasMany = array(
    'Gallery' => array(
        'className' => 'Gallery',
        'foreignKey' => 'usuario_id_usuario'
    )
);

hasAndBelongsToMany (HABTM)

var $hasAndBelongsToMany = array(
    'Archivo' => array(
        'className' => 'Archivo',
        'joinTable' => 'archivos_galleries',
        'foreignKey' => 'galerias_id_galeria',
        'associationForeignKey' => 'files_id_file'
    )
);

Model Behaviors

Tree Behavior (for nested data):

var $actsAs = array('Tree');

ACL Behavior (for authentication):

var $actsAs = array('Acl' => array('requester'));

Validation

Models define validation rules:

var $validate = array(
    'username' => array(
        'rule1' => array(
            'rule' => array('minLength', 4),
            'message' => 'Minimum 4 characters required'
        ),
        'rule2' => array(
            'rule' => array('notEmpty'),
            'message' => '* Required'
        )
    )
);

Views

Location

app/views/

View Structure

views/
├── layouts/
│   └── default.ctp          # Main layout wrapper
├── elements/
│   ├── header.ctp           # Reusable header
│   └── footer.ctp           # Reusable footer
├── helpers/
│   └── custom_helper.php    # View helper classes
├── users/
│   ├── index.ctp           # Users list
│   ├── login.ctp           # Login form
│   ├── add.ctp             # Add user form
│   └── edit.ctp            # Edit user form
└── galleries/
    ├── index.ctp           # Galleries list
    ├── view.ctp            # Single gallery view
    ├── add.ctp             # Add gallery form
    └── edit.ctp            # Edit gallery form

View Naming Convention

File: {action_name}.ctp (e.g., index.ctp, add.ctp)
Location: views/{controller}/{action}.ctp

Automatic View Rendering

CakePHP automatically renders views based on controller/action:

// Controller: GalleriesController
// Action: index()
// View: app/views/galleries/index.ctp

CakePHP Conventions

File Naming

Type	Convention	Example
Controller	`{plural}_controller.php`	`users_controller.php`
Model	`{singular}.php`	`user.php`
View	`{action}.ctp`	`index.ctp`
Helper	`{name}_helper.php`	`form_helper.php`
Component	`{name}_component.php`	`auth_component.php`
Behavior	`{name}_behavior.php`	`tree_behavior.php`

Class Naming

Type	Convention	Example
Controller	`{PluralName}Controller`	`UsersController`
Model	`{SingularName}`	`User`
Helper	`{Name}Helper`	`FormHelper`
Component	`{Name}Component`	`AuthComponent`
Behavior	`{Name}Behavior`	`TreeBehavior`

Database Conventions

Item	Convention	Example
Table	`{plural}_name`	`users`, `galleries`
Primary Key	`id` or `{singular}_id`	`id_usuario`
Foreign Key	`{singular}_id{field}`	`usuario_id_usuario`
Junction Table	`{table1}_{table2}`	`archivos_galleries`

URL Routing

CakePHP follows convention-based routing:

/{controller}/{action}/{param1}/{param2}

Examples:
/users/login
/galleries/view/123
/videos/edit/45

Components

Location: app/controllers/components/ Reusable controller logic shared across multiple controllers.

Built-in Components Used

Auth: User authentication and authorization
Acl: Access Control List management
Session: Session data management
Email: Email sending functionality
PasswordHelper: Custom password utilities

Configuration

Key Configuration Files

app/config/core.php - Core application settings
app/config/database.php - Database connection settings
app/config/routes.php - Custom URL routing rules
app/config/bootstrap.php - Application bootstrap code

Application Flow

┌─────────────────────────────────────────────────┐
│  1. Request: /galleries/view/123               │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│  2. Router parses URL                           │
│     Controller: Galleries                       │
│     Action: view                                │
│     Params: [123]                               │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│  3. AppController::beforeFilter()               │
│     - Initialize Auth component                 │
│     - Check ACL permissions                     │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│  4. GalleriesController::view(123)              │
│     - Query Gallery model                       │
│     - Set view variables                        │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│  5. Gallery->find('first', ['id' => 123])       │
│     - Execute SQL query                         │
│     - Return data array                         │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│  6. Render: views/galleries/view.ctp            │
│     Layout: views/layouts/default.ctp           │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│  7. Response: HTML output to browser            │
└─────────────────────────────────────────────────┘

Best Practices

Controller Best Practices

Keep controllers thin - Business logic belongs in models
Use beforeFilter() for shared setup logic
Redirect after POST - Prevent form resubmission
Set proper flash messages - Inform users of results

Model Best Practices

Define all associations - Enable automatic data fetching
Use validation rules - Ensure data integrity
Add custom find methods - Encapsulate complex queries
Use behaviors - Share logic across models

View Best Practices

Use elements - Reuse common view fragments
Use helpers - Keep views clean of complex logic
Separate layouts - Different designs for different sections
Escape output - Prevent XSS attacks with h()

Database Schema - Complete database structure
Authentication - ACL and Auth implementation

Architecture

API Reference

​Overview

​Directory Structure

​Controllers

​Location

​Available Controllers

​Base Controller (AppController)

​Key Methods

​Controller Naming Convention

​Models

​Location

​Available Models

​Model Naming Convention

​Model Associations

​belongsTo

​hasMany

​hasAndBelongsToMany (HABTM)

​Model Behaviors

​Validation

​Views

​Location

​View Structure

​View Naming Convention

​Automatic View Rendering

​CakePHP Conventions

​File Naming

​Class Naming

​Database Conventions

​URL Routing

​Components

​Built-in Components Used

​Configuration

​Key Configuration Files

​Application Flow

​Best Practices

​Controller Best Practices

​Model Best Practices

​View Best Practices

​Related Documentation

Build docs developers (and LLMs) love

Overview

Directory Structure

Controllers

Location

Available Controllers

Base Controller (AppController)

Key Methods

Controller Naming Convention

Models

Location

Available Models

Model Naming Convention

Model Associations

belongsTo

hasMany

hasAndBelongsToMany (HABTM)

Model Behaviors

Validation

Views

Location

View Structure

View Naming Convention

Automatic View Rendering

CakePHP Conventions

File Naming

Class Naming

Database Conventions

URL Routing

Components

Built-in Components Used

Configuration

Key Configuration Files

Application Flow

Best Practices

Controller Best Practices

Model Best Practices

View Best Practices

Related Documentation