Egulias Provinces Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Install Dependencies Add the bundle and required fixtures to your deps file:

   [EguliasProvincesBundle]
       git=https://github.com/egulias/EguliasProvincesBundle.git
       target=/bundles/Egulias/ProvincesBundle
   
   [doctrine-fixtures]
       git=https://github.com/doctrine/data-fixtures.git
   
   [DoctrineFixturesBundle]
       git=https://github.com/symfony/DoctrineFixturesBundle.git
       target=/bundles/Symfony/Bundle/DoctrineFixturesBundle
   

   Run php bin/vendors install.

2. Register Namespaces Update app/autoload.php:

   $loader->registerNamespaces(array(
       'Egulias' => __DIR__.'/../vendor/bundles',
       'Doctrine\\Common\\DataFixtures' => __DIR__.'/../vendor/doctrine-fixtures/lib',
       'Doctrine\\Common' => __DIR__.'/../vendor/doctrine-common/lib',
   ));
   

3. Enable the Bundle Add to AppKernel.php:

   new Egulias\ProvincesBundle\EguliasProvincesBundle(),
   new Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle(),
   

4. Load Fixtures Create a fixture class (e.g., app/data/fixtures/ProvincesFixtures.php):

   namespace Doctrine\Common\DataFixtures;
   
   use Egulias\ProvincesBundle\DataFixtures\ORM\LoadProvincesData;
   
   class ProvincesFixtures extends OrderFixture implements FixtureInterface {
       public function load(ObjectManager $manager) {
           $loader = new LoadProvincesData();
           $loader->load($manager);
       }
   }
   

   Run:

   php app/console doctrine:fixtures:load
   

5. First Query Use the repository in a controller/service:

   $provinces = $this->getDoctrine()
       ->getRepository('EguliasProvincesBundle:Province')
       ->findAll();
   

Implementation Patterns

Core Workflows

1. Fetching Provinces/Regions

   • By Country: Use the Country entity to filter provinces:

     $country = $this->getDoctrine()->getRepository('EguliasProvincesBundle:Country')->findOneBy(['code' => 'US']);
     $provinces = $country->getProvinces();
     

   • Hierarchical Data: Access regions via provinces:

     $province = $this->getDoctrine()->getRepository('EguliasProvincesBundle:Province')->findOneBy(['code' => 'CA']);
     $region = $province->getRegion();
     

2. Form Integration Use Symfony’s EntityType for dropdowns:

   $builder->add('province', EntityType::class, [
       'class' => 'EguliasProvincesBundle:Province',
       'choice_label' => 'name',
       'query_builder' => function (EntityRepository $er) {
           return $er->createQueryBuilder('p')
               ->where('p.country = :country')
               ->setParameter('country', $this->getDoctrine()->getRepository('EguliasProvincesBundle:Country')->findOneBy(['code' => 'US']));
       },
   ]);
   

3. Caching Provinces Cache frequently accessed data (e.g., all provinces for a country):

   $cache = $this->get('cache.app');
   $key = 'provinces_us';
   $provinces = $cache->get($key, function () use ($country) {
       return $country->getProvinces();
   });
   

4. Custom Fixtures Extend LoadProvincesData to add custom provinces:

   class CustomProvincesFixtures extends LoadProvincesData {
       protected function getProvinces() {
           $provinces = parent::getProvinces();
           $provinces[] = new Province('XX', 'Custom Province', new Country('XX'), new Region('XX'));
           return $provinces;
       }
   }
   

Gotchas and Tips

Pitfalls

1. Fixture Overwrites

   • Running doctrine:fixtures:load without --append will delete and reinsert all provinces/regions.
   • Use --append to avoid data loss:

     php app/console doctrine:fixtures:load --append
     

2. Namespace Conflicts

   • Ensure Egulias namespace is registered in autoload.php; otherwise, autoloading fails silently.

3. Database Schema Mismatch

   • The bundle assumes EguliasProvincesBundle:Province and EguliasProvincesBundle:Region entities exist. If you’ve customized the schema, queries may fail.

4. Case Sensitivity in Codes

   • Province/country codes (e.g., US, CA) are case-sensitive in queries. Use strtoupper() if unsure:

     $province = $repository->findOneBy(['code' => strtoupper('ca')]);
     

Debugging Tips

1. Verify Fixtures Loaded Check if data exists:

   php app/console doctrine:query:sql "SELECT * FROM egulias_province"
   

2. Clear Cache After Fixtures If provinces don’t appear, clear the cache:

   php app/console cache:clear
   

3. Check Entity Manager Ensure the EguliasProvincesBundle is registered in AppKernel before DoctrineFixturesBundle.

Extension Points

1. Custom Province Attributes Extend the Province entity (e.g., add population):

   namespace AppBundle\Entity;
   
   use Egulias\ProvincesBundle\Entity\Province as BaseProvince;
   use Doctrine\ORM\Mapping as ORM;
   
   /** @ORM\Entity */
   class Province extends BaseProvince {
       /** @ORM\Column(type="integer") */
       private $population;
   }
   

2. Override Fixture Data Subclass LoadProvincesData and override getProvinces() to inject custom data (e.g., localized names):

   protected function getProvinces() {
       $provinces = parent::getProvinces();
       foreach ($provinces as $province) {
           $province->setName($province->getName() . ' (Custom)');
       }
       return $provinces;
   }
   

3. Add Validation Use Symfony’s validators to ensure province selection is valid:

   use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
   
   /** @UniqueEntity(fields="code", message="Province code already exists") */
   class Province { ... }
   

4. API Endpoints Expose provinces via API (e.g., with FOSRestBundle):

   # app/config/routing.yml
   egulias_provinces:
       resource: "@EguliasProvincesBundle/Resources/config/routing.yml"
       prefix: /api/provinces