Biz Framework Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require codeages/biz-framework
   

   Add to composer.json under extra:

   "biz-framework": {
       "scan": ["app/Business"]
   }
   

2. Directory Structure Create a Business directory in app/ and follow the framework’s conventions:

   app/
   ├── Business/
   │   ├── [Domain]/
   │   │   ├── [Domain]Service.php
   │   │   ├── [Domain]ServiceInterface.php
   │   │   ├── [Domain]RepositoryInterface.php
   │   │   ├── [Domain]Repository.php
   │   │   ├── [Domain]Model.php
   │   │   └── [Domain]Exception.php
   

3. First Use Case: CRUD Service Define a UserService in app/Business/User/UserService.php:

   namespace App\Business\User;
   
   use Codeages\Biz\Framework\Service;
   
   class UserService extends Service
   {
       public function create(array $data)
       {
           return $this->repository()->create($data);
       }
   }
   

   Register the service in app/Providers/AppServiceProvider.php:

   public function register()
   {
       $this->app->bind(UserServiceInterface::class, UserService::class);
   }
   

4. Autoloading Ensure composer dump-autoload is run after adding new classes.

Implementation Patterns

Core Workflows

1. Service Layer Pattern

• Dependency Injection: Use constructor injection for repositories, managers, or other services.

  class UserService extends Service
  {
      public function __construct(
          UserRepositoryInterface $repository,
          UserValidatorInterface $validator
      ) {
          $this->repository = $repository;
          $this->validator = $validator;
      }
  }
  

• Transaction Management: Wrap business logic in transactions:

  public function updateProfile(array $data)
  {
      $this->transactional(function () use ($data) {
          $this->validator->validate($data);
          $this->repository()->update($data);
      });
  }
  

2. Repository Abstraction

• Implement RepositoryInterface for data access:

  class UserRepository implements UserRepositoryInterface
  {
      public function findByEmail(string $email)
      {
          return User::where('email', $email)->first();
      }
  }
  

• Use Service::repository() to access the bound repository:

  $user = $this->repository()->findByEmail('user@example.com');
  

3. Command Handling

• Define commands in app/Business/[Domain]/Command/:

  namespace App\Business\User\Command;
  
  class CreateUserCommand
  {
      public $name;
      public $email;
  }
  

• Process commands in services:

  public function handle(CreateUserCommand $command)
  {
      return $this->repository()->create([
          'name' => $command->name,
          'email' => $command->email,
      ]);
  }
  

4. Event Dispatching

• Dispatch events after operations:

  public function create(array $data)
  {
      $user = $this->repository()->create($data);
      event(new UserCreated($user));
      return $user;
  }
  

5. Validation

• Use Laravel’s validator or custom validators:

  public function validateCreate(array $data)
  {
      $validator = Validator::make($data, [
          'name' => 'required|string|max:255',
          'email' => 'required|email|unique:users',
      ]);
      if ($validator->fails()) {
          throw new \RuntimeException($validator->errors()->first());
      }
  }
  

Integration Tips

Laravel Facades

• Access services via facades (if registered):

  use App\Facades\UserServiceFacade;
  
  $user = UserServiceFacade::create($data);
  

API Controllers

• Inject services into controllers:

  public function __construct(private UserService $userService) {}
  
  public function store(Request $request)
  {
      return $this->userService->create($request->all());
  }
  

Artisan Commands

• Use services in Artisan commands:

  public function handle()
  {
      $this->userService->seedSampleUsers();
  }
  

Testing

• Mock services in tests:

  $mock = Mockery::mock(UserServiceInterface::class);
  $this->app->instance(UserServiceInterface::class, $mock);
  

Gotchas and Tips

Pitfalls

1. Outdated Documentation

• The package was last updated in 2019. Some Laravel features (e.g., newer dependency injection, facades) may not align perfectly.
• Workaround: Refer to the source code for undocumented features.

2. Service Discovery Limitations

• The scan config in composer.json must match the Business directory structure exactly. Misconfiguration leads to silent failures.
• Fix: Verify the scan path and run composer dump-autoload.

3. No Built-in Caching

• Services/repositories are instantiated on every request. For performance, manually cache instances:

  protected static $repository;
  public function repository()
  {
      return self::$repository ??= app(UserRepositoryInterface::class);
  }
  

4. Lack of Middleware Support

• The framework doesn’t integrate with Laravel middleware. Add middleware in controllers or use a decorator pattern:

  class AuthenticatedUserServiceDecorator implements UserServiceInterface
  {
      public function __construct(private UserService $service) {}
  
      public function create(array $data)
      {
          if (!auth()->check()) {
              throw new \RuntimeException('Unauthenticated');
          }
          return $this->service->create($data);
      }
  }
  

5. No Built-in API Resource Mapping

• Manually map services to API responses. Use Laravel’s Resource classes or DTOs:

  public function toArray($user)
  {
      return [
          'id' => $user->id,
          'name' => $user->name,
          // ...
      ];
  }
  

Debugging Tips

1. Service Not Found

• Check if the service is bound in the container:

  php artisan container:list | grep UserService
  

• Ensure the interface/class is properly namespaced and autoloaded.

2. Repository Not Resolved

• Verify the repository interface is implemented and bound:

  $this->app->bind(UserRepositoryInterface::class, UserRepository::class);
  

3. Transaction Rollback Issues

• Ensure all database operations are within the transactional block. Nested transactions may fail silently.

4. Event Not Firing

• Check if the event is properly dispatched and listeners are registered:

  php artisan event:list
  

Extension Points

1. Custom Service Traits

• Extend base functionality with traits:

  trait SoftDeletesService
  {
      public function softDelete($id)
      {
          return $this->repository()->where('id', $id)->delete();
      }
  }
  

2. Dynamic Repository Binding

• Bind repositories dynamically based on conditions:

  public function repository()
  {
      $type = request()->input('type');
      return $this->app->make("App\\Business\\User\\{$type}Repository");
  }
  

3. Logging Decorator

• Decorate services to add logging:

  class LoggedUserService implements UserServiceInterface
  {
      public function __construct(private UserService $service) {}
  
      public function create(array $data)
      {
          \Log::info('Creating user', $data);
          return $this->service->create($data);
      }
  }
  

4. Custom Exception Handling

• Override exception handling in services:

  public function create(array $data)
  {
      try {
          return $this->repository()->create($data);
      } catch (\Exception $e) {
          throw new UserCreationException($e->getMessage(), $e->getCode());
      }
  }
  

5. Integration with Laravel Scout

• Extend repositories to support search:

  class UserRepository implements UserRepositoryInterface
  {
      public function search(string $query)
      {
          return User::where('name', 'like', "%{$query}%")->get();
      }
  }