Ctrl Common Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ctrl-f5/ctrl-common
   

   Add the package to your config/app.php under providers if it requires service registration.

2. First Use Case: Base Classes The package likely provides utility base classes (e.g., BaseModel, BaseController, BaseService). Start by extending them:

   use CtrlF5\CtrlCommon\BaseModel;
   
   class User extends BaseModel
   {
       // Your model logic here
   }
   

3. Key Entry Points

   • Check the src/ directory for core classes (e.g., BaseModel.php, Traits/).
   • Look for a README.md or docs/ folder for quick-start guides (if available).
   • Run php artisan vendor:publish --provider="CtrlF5\CtrlCommon\ServiceProvider" (if applicable) to publish config/assets.

Implementation Patterns

Common Workflows

1. Model/Entity Abstraction Use BaseModel for shared CRUD, validation, or event handling:

   class Post extends BaseModel
   {
       protected $fillable = ['title', 'content'];
   
       // Inherits traits like `HasTimestamps`, `SoftDeletes`, etc.
   }
   

2. Controller/Service Layer Extend BaseController or BaseService for boilerplate methods:

   use CtrlF5\CtrlCommon\BaseController;
   
   class PostController extends BaseController
   {
       public function index()
       {
           return $this->respondWith($this->postService->all());
       }
   }
   

3. Traits for Reusability Leverage traits like HasApiResources, HandlesValidation, or ManagesEvents:

   use CtrlF5\CtrlCommon\Traits\HandlesValidation;
   
   class UserService
   {
       use HandlesValidation;
   
       public function store(array $data)
       {
           $this->validate($data, ['email' => 'required|email']);
           // ...
       }
   }
   

4. Configuration Overrides Publish and customize the package’s config (if available):

   php artisan vendor:publish --tag=ctrl-common-config
   

   Modify config/ctrl-common.php for default behaviors (e.g., API response formats).

5. Event Handling Use base event classes or listeners for shared logic:

   use CtrlF5\CtrlCommon\Events\BaseEvent;
   
   event(new BaseEvent('user.created', ['user_id' => 1]));
   

Gotchas and Tips

Pitfalls

1. Namespace Collisions The package may use CtrlF5 or CtrlCommon namespaces. Ensure your classes don’t conflict:

   // Avoid:
   namespace CtrlF5\YourApp\Models;
   
   // Prefer:
   namespace App\Models;
   

2. Magic Methods Overrides If BaseModel uses __call or __callStatic, avoid naming conflicts with your methods.

3. Undocumented Traits Some traits might lack PHPDoc or have implicit dependencies. Test thoroughly:

   // Example: Does `HandlesValidation` require a `$validator` property?
   

4. Service Provider Dependencies If the package registers services (e.g., AppServiceProvider), ensure your AppServiceProvider loads after it.

5. Laravel Version Compatibility Check composer.json for Laravel version constraints. Test on your target version.

Debugging Tips

1. Enable Debugging Add to config/ctrl-common.php (if available):

   'debug' => env('CTRL_COMMON_DEBUG', false),
   

2. Log Output Use Laravel’s logging to trace trait/method calls:

   \Log::debug('BaseModel::boot called', ['class' => static::class]);
   

3. Method Override Warnings If extending BaseModel, override methods explicitly to avoid silent failures:

   public function save(array $options = [])
   {
       \Log::info('Custom save logic');
       return parent::save($options);
   }
   

Extension Points

1. Custom Traits Extend existing traits or create new ones in app/Traits/:

   use CtrlF5\CtrlCommon\Traits\BaseTrait;
   
   trait CustomTrait extends BaseTrait
   {
       // Add your logic
   }
   

2. Service Binding Bind interfaces to implementations in AppServiceProvider:

   $this->app->bind(
       \CtrlF5\CtrlCommon\Contracts\Logger::class,
       \App\Services\CustomLogger::class
   );
   

3. Configuration Publishing Publish and modify the package’s config to change defaults:

   php artisan vendor:publish --tag=ctrl-common-config
   

4. Event Listeners Listen to package events in EventServiceProvider:

   protected $listen = [
       \CtrlF5\CtrlCommon\Events\BaseEvent::class => [
           \App\Listeners\HandleBaseEvent::class,
       ],
   ];
   

5. Middleware If the package includes middleware, extend or replace it:

   $router->middleware('ctrl.common', \App\Http\Middleware\CustomMiddleware::class);