Business Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require aescarcha/business "~1"
   composer require friendsofsymfony/rest-bundle jms/serializer-bundle nelmio/api-doc-bundle friendsofsymfony/user-bundle aescarcha/user-bundle league/fractal stof/doctrine-extensions-bundle beberlei/doctrineextensions
   

   (Note: stof/doctrine-extensions-bundle is duplicated in the README; ensure only one is installed.)

2. Enable the Bundle Register in config/bundles.php (Symfony 4+) or app/AppKernel.php (Symfony 3):

   // config/bundles.php
   return [
       // ...
       Aescarcha\BusinessBundle\AescarchaBusinessBundle::class => ['all' => true],
       Stof\DoctrineExtensionsBundle\StofDoctrineExtensionsBundle::class => ['all' => true],
       FOS\RestBundle\FOSRestBundle::class => ['all' => true],
       // ... (other dependencies)
   ];
   

3. Database Setup Run migrations (if provided by the bundle) or manually create tables for:

   • Business entity (likely includes fields like name, address, contact, etc.).
   • Example migration (if none exists, create one):

     php bin/console make:migration
     php bin/console doctrine:migrations:migrate
     

4. First Use Case Use the Business entity in a controller or service:

   use Aescarcha\BusinessBundle\Entity\Business;
   
   // Create a business
   $business = new Business();
   $business->setName('Acme Corp');
   $business->setAddress('123 Main St');
   $em->persist($business);
   $em->flush();
   
   // Fetch via API (if FOSRest is configured)
   $client = static::createClient();
   $response = $client->request('GET', '/api/businesses');
   

Implementation Patterns

Core Workflows

1. CRUD Operations Leverage FOSRestBundle for RESTful endpoints. Example:

   // src/Controller/BusinessController.php
   namespace App\Controller;
   
   use FOS\RestBundle\Controller\FOSRestController;
   use Aescarcha\BusinessBundle\Entity\Business;
   use Symfony\Component\HttpFoundation\Request;
   
   class BusinessController extends FOSRestController
   {
       public function getBusinessesAction()
       {
           $businesses = $this->getDoctrine()
               ->getRepository(Business::class)
               ->findAll();
           return $this->handleView($this->view($businesses, 200));
       }
   
       public function postBusinessAction(Request $request)
       {
           $business = new Business();
           $data = json_decode($request->getContent(), true);
           $business->setName($data['name']);
           $business->setAddress($data['address']);
   
           $em = $this->getDoctrine()->getManager();
           $em->persist($business);
           $em->flush();
   
           return $this->handleView($this->view($business, 201));
       }
   }
   

2. Serialization Use JMSSerializerBundle to customize output:

   # config/packages/jms_serializer.yaml
   jms_serializer:
       metadata:
           directories:
               FOSUser:
                   namespace_prefix: "FOS\\UserBundle"
                   path: "%kernel.project_dir%/vendor/friendsofsymfony/user-bundle/Resources/config/serializer"
               AescarchaBusiness:
                   namespace_prefix: "Aescarcha\\BusinessBundle"
                   path: "%kernel.project_dir%/config/serializer"
   

   Create a custom serializer config (e.g., config/serializer/AescarchaBusiness.Business.yml):

   Aescarcha\BusinessBundle\Entity\Business:
       exclusion_policy: ALL
       properties:
           id:
               expose: true
               type: integer
               groups: [business_read]
           name:
               expose: true
               groups: [business_read]
   

3. API Documentation Use NelmioApiDocBundle to auto-generate Swagger docs:

   # config/packages/nelmio_api_doc.yaml
   nelmio_api_doc:
       documentation:
           info:
               title: Business API
               description: API for managing businesses
               version: 1.0.0
   

   Annotate controllers:

   use Nelmio\ApiDocBundle\Annotation\ApiDoc;
   
   /**
    * @ApiDoc(
    *     resource=true,
    *     description="Get all businesses",
    *     output={"Business[]"}
    * )
    */
   public function getBusinessesAction() { ... }
   

4. Doctrine Extensions Enable soft-deletes or timestamps (via stof/doctrine-extensions):

   // src/Entity/Business.php
   use Gedmo\Mapping\Annotation as Gedmo;
   
   /**
    * @Gedmo\SoftDeleteable(fieldName="deletedAt")
    */
   protected $deletedAt;
   

Integration Tips

1. Event Listeners Extend business logic with Doctrine lifecycle events:

   // src/EventListener/BusinessListener.php
   namespace App\EventListener;
   
   use Aescarcha\BusinessBundle\Entity\Business;
   use Doctrine\Common\EventSubscriber;
   use Doctrine\ORM\Event\LifecycleEventArgs;
   
   class BusinessListener implements EventSubscriber
   {
       public function getSubscribedEvents()
       {
           return ['prePersist', 'preUpdate'];
       }
   
       public function prePersist(LifecycleEventArgs $args)
       {
           $business = $args->getEntity();
           if ($business instanceof Business) {
               $business->setCreatedAt(new \DateTime());
           }
       }
   }
   

2. Validation Add Symfony Validator constraints:

   // src/Entity/Business.php
   use Symfony\Component\Validator\Constraints as Assert;
   
   /**
    * @Assert\NotBlank
    * @Assert\Length(min=3)
    */
   private $name;
   

3. Testing Use PHPUnit with Doctrine fixtures:

   // tests/Functional/BusinessTest.php
   namespace App\Tests\Functional;
   
   use App\Entity\Business;
   use Doctrine\Common\DataFixtures\Executor\ORMExecutor;
   use Doctrine\Common\DataFixtures\Loader;
   use Doctrine\Common\DataFixtures\Purger\ORMPurger;
   
   class BusinessTest extends \Symfony\Bundle\FrameworkBundle\Test\WebTestCase
   {
       public function testCreateBusiness()
       {
           $client = static::createClient();
           $client->request('POST', '/api/businesses', [
               'json' => ['name' => 'Test Business', 'address' => 'Test St']
           ]);
   
           $this->assertEquals(201, $client->getResponse()->getStatusCode());
       }
   }
   

Gotchas and Tips

Pitfalls

1. Bundle Dependency Hell

   • The package requires Symfony 3 and FOSUserBundle, which may conflict with newer Laravel/Lumen projects.
   • Workaround: Fork the bundle and adapt it for Laravel (e.g., use laravel-doctrine for ORM support).

2. Missing Laravel-Specific Features

   • No built-in Laravel service providers, route definitions, or Eloquent integration.
   • Workaround: Manually register entities in config/app.php and create custom controllers.

3. Duplicate Dependencies

   • The README lists stof/doctrine-extensions-bundle twice. Ensure only one is installed to avoid conflicts.

4. No Laravel Migration Support

   • The bundle assumes Symfony migrations (doctrine:migrations). For Laravel:

     php artisan make:migration create_businesses_table
     

     Then manually define the schema (e.g., businesses table with id, name, address, etc.).

5. API Route Conflicts

   • FOSRestBundle may override default Laravel routes. Explicitly define routes in routes/api.php:

     Route::resource('businesses', 'BusinessController', ['only' => ['index', 'store']]);
     

Debugging Tips

1. Check Bundle Registration Verify the bundle is loaded in config/app.php:

   'providers' => [
       // ...
       Aescarcha\BusinessBundle\AescarchaBusinessServiceProvider::class,
   ],
   

2. Doctrine Configuration Ensure config/database.php is properly set up for Doctrine:

   'doctrine' => [
       'default_connection' => env('DB_CONNECTION', 'mysql'),
       'connections' => [
           'mysql' => [
               'driver' => 'pdo_mysql',
               'host' => env('DB_HOST', '127.0.0.1'),
               'database' => env('DB_DATABASE', 'forge'),
               'username' => env('DB_USERNAME',