Common Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require apie/common
   

   Ensure your Laravel project meets the package's PHP version requirements (check composer.json of the package).

2. First Use Case: Creating Objects

   use Apie\Common\Actions\CreateObjectAction;
   
   $action = new CreateObjectAction($persistenceLayer);
   $result = $action->execute($rawData, $resourceName);
   

   • Inject your persistence layer (e.g., Eloquent, Doctrine) into the action.
   • Use $rawData as an array or object representing the resource attributes.

3. Where to Look First

   • Actions: Browse src/Actions/ for available actions like GetListAction, RunAction.
   • Monorepo Docs: Refer to apie-lib-monorepo for high-level architecture.
   • Tests: Check /tests/ for usage examples and edge cases.

Implementation Patterns

Core Workflows

1. Resource CRUD with Actions

   // Create
   $createAction = new CreateObjectAction($persistence);
   $user = $createAction->execute(['name' => 'John'], 'users');
   
   // List with Filtering
   $listAction = new GetListAction($persistence);
   $users = $listAction->execute(['active' => true], 'users');
   

   • Filtering: Pass associative arrays to execute() for filtering (e.g., ['status' => 'published']).

2. RPC-style Operations

   $runAction = new RunAction($service);
   $result = $runAction->execute('calculateTotal', ['items' => $cartItems]);
   

   • Useful for invoking methods on services without tight coupling.

3. Integration with Laravel Services

   // Bind actions to Laravel container
   $app->bind(CreateObjectAction::class, function ($app) {
       return new CreateObjectAction($app->make(PersistenceLayer::class));
   });
   

   • Resolve actions via dependency injection in controllers or services.

Laravel-Specific Tips

• Eloquent Integration:

  $persistence = new EloquentPersistence(User::class);
  $createAction = new CreateObjectAction($persistence);
  

  • Extend Apie\Persistence\PersistenceInterface for custom ORMs.

• API Resource Mapping: Combine with apie/rest-api to auto-generate API endpoints for actions:

  // Example: Map GetListAction to a REST endpoint
  $router->get('/users', function () {
      $action = app()->make(GetListAction::class);
      return $action->execute([], 'users');
  });
  

Gotchas and Tips

Pitfalls

1. Persistence Layer Assumptions

   • Actions assume the persistence layer implements Apie\Persistence\PersistenceInterface.
   • Fix: Create an adapter if using non-standard ORMs (e.g., MongoDB, custom DBAL).

2. Data Validation

   • Actions do not validate input data by default.
   • Workaround: Use Laravel’s ValidatesRequests or FormRequest before passing data to actions.

3. Monorepo Dependency Confusion

   • The package is part of a monorepo. Ensure you’re referencing the correct branch/tag in composer.json:

     "repositories": [
         {
             "type": "vcs",
             "url": "https://github.com/apie-lib/apie-lib-monorepo"
         }
     ]
     

Debugging Tips

• Action Execution Flow: Enable debug logging for actions:

  $action->setLogger(app()->make(\Psr\Log\LoggerInterface::class));
  

• Common Errors:
  • ResourceNotFoundException: Verify $resourceName matches your persistence layer’s entity names.
  • MethodNotFoundException: Check the service/class passed to RunAction for the method name.

Extension Points

1. Custom Actions Extend Apie\Common\Actions\AbstractAction to create reusable logic:

   class ExportAction extends AbstractAction {
       public function execute(array $filters, string $resource) {
           // Custom logic
       }
   }
   

2. Middleware for Actions Wrap actions in middleware for auth/validation:

   $action = new CreateObjectAction($persistence);
   $action->setMiddleware([new AuthMiddleware(), new ValidateMiddleware()]);
   

3. Event Dispatching Trigger events after action execution:

   $action->onSuccess(function ($result) {
       event(new ObjectCreated($result));
   });