masanao-ohba Functional Designer
A specialized skill for creating detailed functional designs and technical specifications for PHP/CakePHP applications.
Core Responsibilities
1. Functional Architecture Design
Component Mapping:
Functional Component Design:
Controllers:
- name: [Controller]Controller
- actions: [list of actions]
- authentication: required|optional
- authorization: role-based permissions
Models:
- Tables: [list of Table classes]
- Entities: [list of Entity classes]
- Associations: [relationships]
- Validation: [rules]
Views:
- Templates: [list of .php files]
- Elements: [reusable components]
- Layouts: [page structures]
Components:
- Custom components needed
- Third-party integrations
2. API Design Specification
RESTful Endpoint Design:
API Endpoint:
method: GET|POST|PUT|DELETE
path: /api/v1/[resource]
authentication: required|optional
request:
headers:
Content-Type: application/json
Authorization: Bearer [token]
body:
field1: type
field2: type
response:
success:
status: 200
body: {data: [...]}
error:
status: 400|401|404|500
body: {error: "message"}
3. Data Flow Design
Request Lifecycle:
1. Route → Controller
2. Controller → Authorization Check
3. Controller → Validation
4. Controller → Model/Service
5. Model → Database
6. Model → Entity
7. Controller → View/JSON Response
Data Transformation:
Input Data → Validation → Business Logic → Entity → Output Format
4. CakePHP Design Patterns
MVC Structure:
src/
├── Controller/
│ ├── AppController.php
│ ├── User/
│ │ └── UsersController.php
│ └── Api/
│ └── UsersController.php
├── Model/
│ ├── Table/
│ │ └── UsersTable.php
│ └── Entity/
│ └── User.php
├── View/
│ └── User/
│ └── Users/
│ ├── index.php
│ ├── view.php
│ ├── add.php
│ └── edit.php
└── Service/
└── UserService.php
5. Design Document Template
# Functional Design: [Feature Name]
## 1. Overview
### Purpose
[Brief description of what this feature does]
### Scope
- In Scope: [what's included]
- Out of Scope: [what's not included]
## 2. Functional Components
### 2.1 Controllers
#### [Name]Controller
- **Purpose**: [description]
- **Actions**:
- index(): List all records
- view($id): Display single record
- add(): Create new record
- edit($id): Update existing record
- delete($id): Remove record
### 2.2 Models
#### [Name]Table
- **Fields**:
- id (integer, primary key)
- name (string, required)
- status (integer, default: 1)
- created (datetime)
- modified (datetime)
- **Associations**:
- belongsTo: [Parent]
- hasMany: [Children]
- **Validation Rules**:
- name: notEmpty, maxLength(255)
- email: email, unique
### 2.3 Business Logic
```php
// Pseudo-code for main logic
public function processOrder($data) {
// 1. Validate input
// 2. Calculate totals
// 3. Check inventory
// 4. Create order
// 5. Send notifications
// 6. Return result
}
3. Database Design
Tables
CREATE TABLE orders (
id INT PRIMARY KEY AUTO_INCREMENT,
user_id INT NOT NULL,
total DECIMAL(10,2),
status INT DEFAULT 1,
created DATETIME,
modified DATETIME,
FOREIGN KEY (user_id) REFERENCES users(id)
);
4. API Specification
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/orders | List orders |
| GET | /api/orders/{id} | Get order details |
| POST | /api/orders | Create order |
| PUT | /api/orders/{id} | Update order |
| DELETE | /api/orders/{id} | Delete order |
5. Security Considerations
- Authentication: JWT/Session
- Authorization: Role-based (Admin, User, Guest)
- Data Validation: Server-side validation for all inputs
- SQL Injection: Use ORM query builder
- XSS Prevention: Escape output in views
6. Performance Considerations
- Pagination for large datasets
- Eager loading for associations
- Query optimization
- Caching strategy
## Design Patterns
### 1. Service Layer Pattern
```php
// Service class for complex business logic
class OrderService
{
private $Orders;
private $Inventory;
public function createOrder($data)
{
// Complex logic separated from controller
}
}
2. Repository Pattern
// Custom finder methods in Table class
class OrdersTable extends Table
{
public function findPending(Query $query, array $options)
{
return $query->where(['status' => 'pending']);
}
}
3. Event-Driven Design
// Event listeners for decoupled components
EventManager::instance()->on(
'Model.Order.afterCreate',
function ($event, $order) {
// Send notification
// Update inventory
// Log activity
}
);
Integration Patterns
1. Multi-Tenant Design
// Company-specific data access
public function getCompanyOrders($companyId)
{
$conn = $this->MessageDeliveryDbAccessor
->getUserMessageDeliveryDbConnection($companyId);
$this->Orders->setConnection($conn);
return $this->Orders->find()->all();
}
2. Plugin Integration
Plugins to integrate:
- Authentication: CakePHP/Authentication
- Authorization: CakePHP/Authorization
- PDF Generation: FriendsOfCake/CakePdf
- Email: Built-in Mailer
3. Queue Processing
// Async job processing
QueueManager::push(SendEmailJob::class, [
'to' => $user->email,
'template' => 'order_confirmation',
'data' => $orderData
]);
Output Examples
Example 1: User Management Design
Feature: User Management
Controllers:
UsersController:
- index: List users with pagination
- add: Create user with role assignment
- edit: Update user profile
- delete: Soft delete with audit log
Models:
UsersTable:
fields: [id, email, password, role_id, status]
associations:
- belongsTo: Roles
- hasMany: Orders
validation:
- email: unique, valid format
- password: min 8 chars, complexity rules
Security:
- Password hashing: bcrypt
- Session management: 30 min timeout
- Role-based access: Admin, Manager, User
Example 2: Reporting Module Design
Feature: Sales Reporting
Components:
ReportGenerator:
- generateMonthly(): Create monthly report
- exportPdf(): Convert to PDF
- sendEmail(): Email to stakeholders
Data Sources:
- Orders table
- OrderItems table
- Products table
Performance:
- Use database views for complex queries
- Cache generated reports for 24 hours
- Background job for large reports
Quality Criteria
Good Design:
- Clear separation of concerns
- Reusable components
- Scalable architecture
- Follows CakePHP conventions
- Testable code structure
Poor Design:
- Business logic in controllers
- Direct database queries in views
- Tight coupling between components
- Ignoring framework conventions
Best Practices
- Follow Conventions: Use CakePHP naming conventions
- Keep Controllers Thin: Move logic to models/services
- Use Behaviors: Share functionality between models
- Implement Interfaces: Define contracts for services
- Document Decisions: Explain why, not just what
Remember: Good design makes implementation straightforward and maintenance easy.