singleloginsystem/app/Services

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.