Person Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require chill-project/person
   

   Register the bundle in config/bundles.php (Symfony) or config/app.php (Laravel wrapper if available):

   Chill\PersonBundle\ChillPersonBundle::class => ['all' => true],
   

2. Database Migration Run the bundle’s migrations (if provided):

   php artisan migrate
   

   Check src/Chill/PersonBundle/Resources/migrations/ for schema definitions.

3. First Use Case Fetch a person by ID:

   use Chill\PersonBundle\Entity\Person;
   
   $person = app(\Chill\PersonBundle\Repository\PersonRepository::class)
       ->find(1);
   

Implementation Patterns

Core Workflows

1. CRUD Operations Use the repository pattern for all interactions:

   // Create
   $person = new Person();
   $person->setFirstName('John');
   $person->setLastName('Doe');
   $repository->save($person);
   
   // Update
   $person->setEmail('[email protected]');
   $repository->save($person);
   
   // Delete
   $repository->remove($person);
   

2. Querying Leverage DQL or QueryBuilder:

   $adults = $repository->createQueryBuilder('p')
       ->where('p.age >= :age')
       ->setParameter('age', 18)
       ->getQuery()
       ->getResult();
   

3. Events & Lifecycle Subscribe to bundle events (if documented):

   // Example: Listen for person creation
   event(new \Chill\PersonBundle\Event\PersonCreatedEvent($person));
   

Integration Tips

• Validation: Extend Person entity with custom validation rules (e.g., unique:persons,email).
• APIs: Use Symfony Serializer or Laravel’s Resource classes to format responses:

  return new PersonResource($person);
  

• Testing: Mock the PersonRepository in unit tests:

  $this->mock(PersonRepository::class)->shouldReceive('find')->andReturn($mockPerson);
  

Gotchas and Tips

Pitfalls

1. Archived Status

   • The package is archived (no active maintenance). Verify compatibility with your Laravel version (e.g., test against Symfony 5.4+ if bundled).
   • Fork the repo if critical fixes are needed.

2. Documentation Gaps

   • Official docs (chill.readthedocs.org) may lack Laravel-specific examples. Cross-reference with Symfony bundle docs.
   • Workaround: Inspect src/Chill/PersonBundle/Tests/ for usage patterns.

3. Entity Configuration

   • If using Doctrine ORM, ensure your config/packages/doctrine.yaml includes:

     orm:
         mappings:
             chill_person:
                 type: attribute
                 dir: "%kernel.project_dir%/vendor/chill-project/person/src/Entity"
                 prefix: "Chill\PersonBundle\Entity"
                 alias: ChillPerson
     

Debugging Tips

• Entity Not Found: Verify the Person entity is properly mapped in Doctrine:

  php bin/console doctrine:schema:validate
  

• Event Dispatching: Check if events are fired by adding a listener:

  public function onPersonCreated(PersonCreatedEvent $event) {
      \Log::info('Person created:', [$event->getPerson()->getId()]);
  }
  

• Performance: Add indexes to frequently queried fields (e.g., email, last_name) via custom migrations.

Extension Points

1. Custom Fields Extend the Person entity (use inheritance or traits):

   namespace App\Entity;
   
   use Chill\PersonBundle\Entity\Person as BasePerson;
   
   class Person extends BasePerson {
       #[ORM\Column]
       private ?string $customField = null;
   }
   

2. Repository Overrides Create a custom repository and bind it in services:

   # config/services.yaml
   App\Repository\CustomPersonRepository:
       arguments: ['@entity_manager']
       tags: ['doctrine.repository_service']
   

3. API Resources Override serialization groups in Person:

   #[Groups(['default', 'admin'])]
   public function getFullName(): string {
       return $this->firstName . ' ' . $this->lastName;
   }