Products Brand Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require baks-dev/products-brand
   

   Ensure your composer.json includes "minimum-stability": "dev" if using pre-release versions.

2. Publish Assets (if needed) Run the asset installer to copy JS/CSS/images to public/:

   php artisan baks:assets:install
   

   Verify assets appear in public/vendor/baks/products-brand/.

3. Database Setup Run migrations to create brand-related tables:

   php artisan doctrine:migrations:diff
   php artisan doctrine:migrations:migrate
   

4. Load Fixtures (Optional) Populate default admin roles for brand management:

   php artisan doctrine:fixtures:load --append
   

5. First Use Case: Create a Brand Use the Brand model (likely Baks\ProductsBrand\Entity\Brand) in a controller:

   use Baks\ProductsBrand\Entity\Brand;
   use Baks\ProductsBrand\Repository\BrandRepository;
   
   public function createBrand(BrandRepository $brandRepo) {
       $brand = new Brand();
       $brand->setName('Example Brand');
       $brand->setSlug('example-brand');
       $brandRepo->save($brand);
       return redirect()->route('brands.index');
   }
   

Implementation Patterns

Core Workflows

1. CRUD Operations

   • Use the Brand entity and BrandRepository for all database interactions.
   • Example: List brands with pagination:

     $brands = $brandRepo->findAllWithPagination($page, $limit);
     

2. Asset Management

   • Store brand logos/images in public/uploads/brands/ (or a custom path).
   • Use the BrandAssetService (if available) to handle uploads:

     $assetService = app(Baks\ProductsBrand\Service\BrandAssetService::class);
     $assetService->uploadLogo($brand, $request->file('logo'));
     

3. API Integration

   • Expose brand data via API using Symfony Serializer:

     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
     $normalizer = new ObjectNormalizer();
     $brandData = $normalizer->normalize($brand);
     

4. Event-Driven Logic

   • Listen for brand events (e.g., BrandCreatedEvent) to trigger side effects:

     event(new BrandCreatedEvent($brand));
     

5. Form Handling

   • Use the BrandType form (if provided) in controllers:

     $form = $this->createForm(Baks\ProductsBrand\Form\BrandType::class, $brand);
     

Integration Tips

1. Service Container Binding Bind custom services in config/services.php:

   'baks.products-brand' => [
       'asset_path' => 'custom/uploads/brands',
   ],
   

   Access via config('services.baks.products-brand.asset_path').

2. Custom Validation Extend the Brand entity validator (e.g., BrandValidator) or add constraints:

   use Symfony\Component\Validator\Constraints as Assert;
   $brand->setSlug($request->slug);
   // Add custom validation in your controller/form.
   

3. Localization Translate brand names/descriptions using Symfony’s translation system:

   $brand->setName($translator->trans('brand.example'));
   

4. Testing Use the BrandFactory (if available) for unit tests:

   $brand = BrandFactory::create(['name' => 'Test Brand']);
   $this->assertEquals('test-brand', $brand->getSlug());
   

Gotchas and Tips

Pitfalls

1. Missing Migrations

   • Always run doctrine:migrations:diff and migrate after updating the package.
   • Fix: Rollback and re-migrate if schema errors occur:

     php artisan doctrine:migrations:rollback
     php artisan doctrine:migrations:migrate
     

2. Asset Path Conflicts

   • If assets don’t load, check public/ permissions (chmod -R 755 public/).
   • Fix: Re-run baks:assets:install or manually copy files.

3. Fixture Overwrites

   • --append flag is critical for fixtures to avoid data loss:

     php artisan doctrine:fixtures:load --append
     

4. Translation Keys

   • Hardcoded strings in the package may not be translatable. Override them in your translations/ files:

     en:
         brand:
             fields:
                 name: "Brand Name"
     

5. PHP 8.1+ Strictness

   • The package enforces PHP 8.1+. Use strict_types=1 in your project.

Debugging

1. Doctrine Events Enable SQL logging in .env:

   DOCTRINE_DQL_LOGGING=true
   DOCTRINE_ORM_LOGGING=true
   

2. Event Listeners Check if events are fired by adding a temporary listener:

   $dispatcher->addListener(BrandEvents::BRAND_CREATED, function ($event) {
       error_log('Brand created: ' . $event->getBrand()->getName());
   });
   

3. Asset Loading Verify the asset path in config/services.php matches the actual public/ structure.

Extension Points

1. Custom Brand Fields Extend the Brand entity:

   namespace App\Entity;
   use Baks\ProductsBrand\Entity\Brand as BaseBrand;
   
   class Brand extends BaseBrand {
       #[ORM\Column]
       private ?string $customField = null;
   }
   

2. Override Templates Copy the package’s Twig templates to resources/views/vendor/baks/products-brand/ to customize.

3. Add New Features Create a custom service and bind it in config/services.php:

   'baks.products-brand.services' => [
       'custom_service' => App\Service\CustomBrandService::class,
   ],
   

4. API Resources Extend the BrandResource (if provided) for custom API responses:

   namespace App\Resources;
   use Baks\ProductsBrand\Resources\BrandResource as BaseResource;
   
   class BrandResource extends BaseResource {
       public function toArray($context = [])
       {
           $data = parent::toArray($context);
           $data['custom_field'] = $this->resource->getCustomField();
           return $data;
       }
   }
   

5. Console Commands Extend existing commands (e.g., BrandCommand) or create new ones in app/Console/Commands.