Paddock Core Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require badpixxel/paddock-core
   

   Ensure badpixxel/paddock-core is added to config/app.php under providers.

2. Publish Configuration

   php artisan vendor:publish --provider="Badpixxel\PaddockCore\PaddockCoreServiceProvider" --tag="config"
   

   This generates config/paddock.php with default settings.

3. Basic Setup Register the service provider in config/app.php:

   Badpixxel\PaddockCore\PaddockCoreServiceProvider::class,
   

4. First Use Case: Model Binding Bind a model to a route parameter (e.g., User):

   use Badpixxel\PaddockCore\Traits\PaddockBindable;
   
   class UserController extends Controller
   {
       use PaddockBindable;
   
       public function show($id)
       {
           $user = $this->bindModel(User::class, $id);
           // Use $user...
       }
   }
   

Implementation Patterns

Core Workflows

1. Model Binding

   • Use PaddockBindable trait for automatic model binding in controllers:

     $model = $this->bindModel(Model::class, $id, ['column' => 'value']);
     

   • Supports eager loading:

     $model = $this->bindModel(Model::class, $id, [], ['with' => ['relation']]);
     

2. API Resource Handling

   • Transform models to API responses with PaddockResource:

     use Badpixxel\PaddockCore\Resources\PaddockResource;
     
     class UserResource extends PaddockResource
     {
         public function toArray($request)
         {
             return [
                 'id' => $this->id,
                 'name' => $this->name,
             ];
         }
     }
     

   • Use in controllers:

     return new UserResource($user);
     

3. Request Validation

   • Extend PaddockFormRequest for validation:

     use Badpixxel\PaddockCore\Http\Requests\PaddockFormRequest;
     
     class StoreUserRequest extends PaddockFormRequest
     {
         public function rules()
         {
             return [
                 'name' => 'required|string|max:255',
                 'email' => 'required|email',
             ];
         }
     }
     

4. Service Layer Integration

   • Use PaddockService trait for dependency injection:

     use Badpixxel\PaddockCore\Traits\PaddockService;
     
     class UserService
     {
         use PaddockService;
     
         public function create(array $data)
         {
             return User::create($data);
         }
     }
     

Integration Tips

• Laravel Mix/Inertia.js: Pair with PaddockResource for seamless frontend-backend data flow.
• API Versioning: Use PaddockResource to version API responses without duplicating logic.
• Testing: Mock PaddockBindable and PaddockService traits in unit tests:

  $controller->partialMock(PaddockBindable::class, ['bindModel']);
  

Gotchas and Tips

Pitfalls

1. Model Binding Scope

   • Ensure PaddockBindable respects Laravel’s default model binding scope (e.g., Route::model()). Override with:

     $this->bindModel(Model::class, $id, [], ['scope' => 'active']);
     

2. Resource Caching

   • PaddockResource does not cache responses by default. For performance, implement shouldCache():

     public function shouldCache()
     {
         return true;
     }
     

3. Validation Rules

   • Custom PaddockFormRequest rules may conflict with Laravel’s built-in validation. Use merge() to combine:

     public function rules()
     {
         return array_merge(parent::rules(), ['custom_field' => 'required']);
     }
     

4. Service Provider Conflicts

   • If using multiple Paddock-like packages, ensure service provider binding order in config/app.php.

Debugging

• Binding Failures: Check config/paddock.php for bindable_models whitelist. Add your model:

  'bindable_models' => [
      'App\Models\User',
      'App\Models\Post',
  ],
  

• Resource Serialization: Use dd($this->resource) in toArray() to debug output.

Extension Points

1. Custom Binders Override PaddockBindable::resolveModel() for custom logic:

   protected function resolveModel($model, $id, $extra = [], $options = [])
   {
       if ($model === User::class && $id === 'guest') {
           return User::where('email', '[email protected]')->first();
       }
       return parent::resolveModel($model, $id, $extra, $options);
   }
   

2. Dynamic Resources Extend PaddockResource for dynamic fields:

   public function toArray($request)
   {
       return array_merge(
           parent::toArray($request),
           ['dynamic_field' => $request->input('dynamic_field')]
       );
   }
   

3. Middleware Integration Use PaddockMiddleware for pre-binding checks:

   class EnsureActiveUser
   {
       use PaddockMiddleware;
   
       public function handle($request, Closure $next)
       {
           $user = $this->bindModel(User::class, $request->user()->id);
           if (!$user->isActive()) {
               abort(403);
           }
           return $next($request);
       }
   }