0de768e924
- Added comprehensive documentation for `ConnectionProviderService`, outlining architectural design, coding standards, and operational flows. - Enhanced `ConnectionProvider` and `ConnectedApp` models with Spatie activity logging configuration for detailed CRUD activity tracking. - Updated delete methods in service classes to include audit logs and cascade behavior refinement. - Revised activity log migration schema for stricter typing and method structure.
99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# Service Class Guidelines & Flow: ConnectionProviderService
|
|
|
|
This document outlines the architectural flow, design patterns, and coding guidelines implemented within the
|
|
ConnectionProviderService class. It serves as a reference for maintaining this service and acts as a blueprint for
|
|
creating similar service classes within the application.
|
|
|
|
## 1. General Coding Guidelines
|
|
|
|
The service class adheres to several strict Laravel and general PHP best practices to ensure robustness, predictability,
|
|
and maintainability.
|
|
|
|
1. Strict Typing: The file declares strict_types=1 at the top. All method arguments and return values must have explicit
|
|
type hints.
|
|
|
|
2. Data Transfer Objects (DTOs): Instead of passing raw arrays or generic Laravel Request objects, the service utilizes
|
|
strongly typed DTOs (via Spatie\LaravelData).
|
|
|
|
Input: StoreConnectionProviderRequestData
|
|
|
|
Output: ConnectionProviderData, PaginatedDataCollection
|
|
|
|
3. Database Transactions: All data mutation methods (Create, Update, Delete) are wrapped within DB::transaction()
|
|
closures to guarantee database integrity. If any part of the operation fails, the entire transaction rolls back.
|
|
|
|
4. The #[NoDiscard] Attribute: Read-only methods (search, getAll, getProvider) utilize the #[NoDiscard] attribute. This
|
|
strictly enforces that the calling code must capture and use the returned data, preventing logic leaks where a
|
|
developer calls a getter but ignores the result.
|
|
|
|
5. Explicit Exception Documentation: Every method that can throw an exception documents it clearly in the PHPDoc block (
|
|
e.g., @throws ModelNotFoundException, @throws Throwable).
|
|
|
|
## 2. Architectural Flow by Operation
|
|
|
|
### A. Read Operations
|
|
|
|
Read operations are optimized for memory and performance by explicitly selecting only the necessary columns.
|
|
|
|
* search(string $value)
|
|
|
|
Flow: Initiates an Eloquent query targeting the slug or name columns using a LIKE operator (%value%).
|
|
|
|
Returns: An Eloquent Collection of ConnectionProvider models.
|
|
|
|
* getAll()
|
|
|
|
Flow: Queries the database selecting only id, name, and slug. It then paginates the results.
|
|
|
|
Returns: The paginated result is transformed into a PaginatedDataCollection containing ConnectionProviderData objects.
|
|
|
|
* getProvider(string $slug)
|
|
|
|
Flow: Looks up a specific provider by its slug, selecting only id, name, and slug.
|
|
|
|
Returns: Transforms the found model into a single ConnectionProviderData object.
|
|
|
|
### B. Write Operations (Create / Update)
|
|
|
|
Write operations rely on DTOs to ensure the data being inserted or updated is pre-validated and formatted correctly.
|
|
|
|
* create(StoreConnectionProviderRequestData $data)
|
|
|
|
Flow: Opens a DB transaction. Converts the validated DTO to an array and passes it to the Eloquent create method.
|
|
|
|
* update(string $slug, StoreConnectionProviderRequestData $data)
|
|
|
|
Flow: Opens a DB transaction. Locates the model by its slug and updates it using the array representation of the provided DTO.
|
|
|
|
### C. Delete Operation (Cascade & Logging)
|
|
|
|
The delete method contains the most complex flow, handling cascading soft-deletes and custom audit logging.
|
|
|
|
delete(string $slug)
|
|
|
|
Step 1 (Find): Locates the ConnectionProvider by slug or throws a ModelNotFoundException.
|
|
|
|
Step 2 (Fetch Relations): Retrieves the id and name of all associated connectedApps to preserve their state for the audit log.
|
|
|
|
Step 3 (Cascade Delete): Performs a mass query deletion ($provider->connectedApps()->delete()).
|
|
|
|
Note: Because this is a mass delete, individual model events for ConnectedApp will not fire.
|
|
|
|
Step 4 (Provider Delete): Disables default logging on the provider to prevent redundant logs, then deletes the provider.
|
|
|
|
Step 5 (Audit Log): Manually triggers a comprehensive Spatie Activity log (provider_cascade_deleted). It records the specific user (:causer.name), the provider details, and an array of the deleted child apps.
|
|
|
|
## 3. Performance & Security Best Practices
|
|
|
|
When extending this service or building new ones, adhere strictly to the following patterns demonstrated in the code:
|
|
|
|
1. Selective Querying: Always use ```$model->select(['id', 'column_name'])``` when returning data to the frontend or
|
|
DTOs to avoid memory bloat from fetching unused columns (e.g., timestamps, hidden credentials).
|
|
|
|
2. Route/Key Binding vs. Service Lookups: Notice that update, delete, and getProvider accept a primitive string
|
|
```$slug / $id``` rather than an already-resolved Model. This keeps the service decoupled from HTTP routing logic and
|
|
allows it to be called safely from CLI commands or background jobs.
|
|
|
|
3. Auditable Actions: For destructive actions (like cascades), always disable automatic noise and implement a custom,
|
|
highly detailed activity log so system administrators can trace exactly what data was removed and by whom.
|