Address Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dywee/address-bundle
   

2. Register Bundle Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       Dywee\AddressBundle\DyweeAddressBundle::class => ['all' => true],
   ];
   

   (For Symfony 3, update AppKernel.php as shown in README.)

3. Required Dependencies Install mandatory bundles:

   composer require knplabs/knp-paginator-bundle misd/phone-number-bundle
   

4. Doctrine Configuration Add to config/packages/doctrine.yaml:

   doctrine:
       dbal:
           types:
               phone_number: Misd\PhoneNumberBundle\Doctrine\DBAL\Types\PhoneNumberType
   

5. First Use Case Generate a CRUD controller for addresses:

   php bin/console make:crud Address Dywee\AddressBundle\Entity\Address
   

   (Assumes the bundle provides an Address entity—verify via src/Dywee/AddressBundle/Entity/Address.php.)

Implementation Patterns

Core Workflows

1. Address Management

   • Create/Update: Use the bundle’s form types (e.g., Dywee\AddressBundle\Form\AddressType) for standardized address fields (street, city, postal code, etc.).

     $form = $this->createForm(AddressType::class, $address);
     

   • Validation: Leverage built-in constraints (e.g., @Assert\Country, @Assert\PostalCode) for validation.

2. Pagination Use KnpPaginatorBundle for address listings:

   $addresses = $this->getDoctrine()
       ->getRepository(Address::class)
       ->findAll();
   $pagination = $this->get('knp_paginator')
       ->paginate($addresses, $request->query->getInt('page', 1));
   

   Render with Twig:

   {% for address in pagination %}
       {{ address.street }}, {{ address.postalCode }}
   {% endfor %}
   {{ knp_pagination_render(pagination) }}
   

3. Phone Number Integration Pair with MisdPhoneNumberBundle for phone validation/storage:

   $address->setPhoneNumber(new PhoneNumber('+1234567890'));
   

4. Entity Extensions Extend the Address entity (e.g., add custom fields):

   namespace App\Entity;
   
   use Dywee\AddressBundle\Entity\Address as BaseAddress;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class Address extends BaseAddress {
       #[ORM\Column]
       private ?string $customField = null;
   }
   

Gotchas and Tips

Pitfalls

1. Bundle Maturity

   • No Active Maintenance: The package has 0 stars and 0 dependents, indicating untested real-world use. Validate functionality via tests or fork the repo.
   • Symfony 3 Focus: Assumes Symfony 3.x conventions (e.g., AppKernel). For Symfony 4/5, adapt configurations (e.g., config/bundles.php instead of AppKernel.php).

2. Missing Documentation

   • Entity Structure: The Address entity’s fields aren’t documented. Inspect src/Dywee/AddressBundle/Entity/Address.php to confirm available properties (e.g., street, city, country).
   • Form Customization: Override form themes or types if default fields (e.g., country) require localization (e.g., ISO 3166-1 alpha-2 codes).

3. Dependency Conflicts

   • KnpPaginatorBundle: Ensure version ^2.5 is compatible with your Symfony version (check KnpPaginator’s docs).
   • PhoneNumberBundle: The phone_number DBAL type may conflict with other Doctrine types. Test migrations thoroughly.

4. Pagination Quirks

   • Sliding Template: The default sliding.html.twig template may not render correctly without CSS. Override or extend:

     # templates/KnpPaginator/sliding.html.twig
     {% extends 'KnpPaginatorBundle:Pagination:sliding.html.twig' %}
     {% block pagination_link %}
         <a href="{{ path }}">{{ number }}</a>
     {% endblock %}
     

Debugging Tips

1. Entity Mapping Issues If addresses fail to save, check:

   • Doctrine mappings with:

     php bin/console doctrine:schema:validate
     

   • Entity annotations (e.g., @ORM\Column for postalCode).

2. Form Errors Clear cache and validate forms:

   php bin/console cache:clear
   

   Dump form errors in Twig:

   {% for error in form.errors %}
       {{ error.message }}
   {% endfor %}
   

3. Country/Postal Code Validation Extend validation for specific locales:

   use Symfony\Component\Validator\Constraints as Assert;
   
   #[Assert\Country(code: 'US')] // Restrict to US
   private ?string $countryCode;
   

Extension Points

1. Custom Address Types Create a subclassed form type for specialized addresses (e.g., InternationalAddressType):

   namespace App\Form;
   
   use Dywee\AddressBundle\Form\AddressType;
   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class InternationalAddressType extends AbstractType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           parent::buildForm($builder, $options);
           $builder->add('countryCode', TextType::class, [
               'constraints' => [new Assert\Country()],
           ]);
       }
   }
   

2. Repository Extensions Add custom queries to the AddressRepository:

   namespace App\Repository;
   
   use Dywee\AddressBundle\Repository\AddressRepository as BaseRepository;
   
   class AddressRepository extends BaseRepository {
       public function findByCity(string $city) {
           return $this->createQueryBuilder('a')
               ->where('a.city = :city')
               ->setParameter('city', $city)
               ->getQuery()
               ->getResult();
       }
   }
   

3. Twig Extensions Add helper functions for address formatting:

   // src/Twig/AppExtension.php
   namespace App\Twig;
   
   use Twig\Extension\AbstractExtension;
   use Twig\TwigFunction;
   
   class AppExtension extends AbstractExtension {
       public function getFunctions() {
           return [
               new TwigFunction('format_address', [$this, 'formatAddress']),
           ];
       }
   
       public function formatAddress($address) {
           return sprintf(
               '%s, %s %s, %s',
               $address->getStreet(),
               $address->getPostalCode(),
               $address->getCity(),
               $address->getCountry()
           );
       }
   }
   

   Use in Twig:

   {{ format_address(address) }}