Relay Base Person Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dbp/relay-base-person-bundle
   

   Publish the bundle’s configuration (if needed):

   php artisan vendor:publish --provider="Dbp\RelayBasePersonBundle\RelayBasePersonBundle" --tag="config"
   

2. First Use Case: Querying a Base Person The bundle provides a PersonRepository for querying base person records. Inject it into a service or controller:

   use Dbp\RelayBasePersonBundle\Repository\PersonRepository;
   
   class PersonController extends Controller
   {
       public function __construct(private PersonRepository $personRepository) {}
   
       public function show(int $id)
       {
           $person = $this->personRepository->find($id);
           return response()->json($person);
       }
   }
   

3. Key Configuration Check config/relay_base_person.php for:

   • Database connection settings (if using custom tables).
   • Default query scopes (e.g., activePersonsOnly).

4. First Query Fetch all active persons with pagination:

   $persons = $this->personRepository->newQuery()
       ->active()
       ->paginate(10);
   

Implementation Patterns

Core Workflows

1. Repository-Based CRUD The bundle follows a repository pattern. Extend PersonRepository for custom logic:

   namespace App\Repositories;
   
   use Dbp\RelayBasePersonBundle\Repository\PersonRepository as BasePersonRepository;
   
   class CustomPersonRepository extends BasePersonRepository
   {
       public function findByEmail(string $email)
       {
           return $this->newQuery()->where('email', $email)->first();
       }
   }
   

2. Event-Driven Extensions Listen to bundle events (e.g., PersonCreated) to hook into workflows:

   use Dbp\RelayBasePersonBundle\Event\PersonCreated;
   
   Event::listen(PersonCreated::class, function (PersonCreated $event) {
       // Send welcome email, log activity, etc.
   });
   

3. GraphQL Integration If using Relay (GraphQL), the bundle provides base types. Extend them in your schema:

   type Person implements Node {
       id: ID!
       name: String!
       # ... extend with custom fields
   }
   

4. API Resource Transformation Use PersonResource (if provided) to shape API responses:

   use Dbp\RelayBasePersonBundle\Http\Resources\PersonResource;
   
   return PersonResource::collection($persons);
   

Integration Tips

• Database Migrations: The bundle may include migrations. Check vendor/dbp/relay-base-person-bundle/migrations for reference.
• Testing: Use the PersonFactory (if available) for seeding tests:

  $person = PersonFactory::new()->create();
  

• Caching: Enable query caching via the repository’s remember() method:

  $person = $this->personRepository->remember(3600)->find($id);
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions The bundle uses Dbp\RelayBasePersonBundle namespace. Avoid naming conflicts with:

   use Dbp\RelayBasePersonBundle as RelayPerson;
   

2. Missing Documentation

   • The docs-dev/README.md may lack examples for complex extensions. Refer to the Relay docs for GraphQL-specific patterns.
   • Workaround: Inspect the bundle’s src/ for undocumented features (e.g., custom query builders).

3. AGPL License Implications

   • The AGPL-3.0 license requires open-sourcing modified versions. Document dependencies and changes if extending the bundle.

4. Query Performance

   • Avoid eagerLoad('*') on large datasets. Use explicit relationships:

     $person = $this->personRepository->with(['address', 'roles'])->find($id);
     

Debugging

• Enable Query Logging Add to config/logging.php:

  'channels' => [
      'query' => [
          'driver' => 'single',
          'path' => storage_path('logs/query.log'),
          'level' => 'debug',
      ],
  ],
  

  Then log queries in repositories:

  \DB::enableQueryLog();
  $this->newQuery()->get();
  \Log::debug('Queries:', \DB::getQueryLog());
  

• Common Errors

  • "Table not found": Ensure the database connection in config/relay_base_person.php matches your schema.
  • GraphQL Schema Conflicts: Clear cached schemas after extending types:

    php artisan cache:clear
    

Extension Points

1. Custom Fields Add fields via migrations or entity extensions:

   // app/Extensions/PersonExtension.php
   namespace App\Extensions;
   
   use Dbp\RelayBasePersonBundle\Entity\Person;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class PersonExtension
   {
       #[ORM\Column(type: 'string', nullable: true)]
       private ?string $customField = null;
   
       // Getters/setters...
   }
   

2. Override Services Bind custom implementations in config/app.php:

   'bindings' => [
       Dbp\RelayBasePersonBundle\Repository\PersonRepository::class => App\Repositories\CustomPersonRepository::class,
   ],
   

3. Add Validation Extend the Person entity with Symfony Validator constraints:

   use Symfony\Component\Validator\Constraints as Assert;
   
   #[Assert\Email]
   private ?string $email = null;
   

4. Localization Override translation files in resources/lang/ to customize labels (e.g., relay_base_person.validation.email).