Ip Filter Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require coosos/ip-filter-bundle
   

   Ensure your composer.json meets the requirements (PHP 7.1+, Symfony 4/5, Doctrine 2.6+).

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       Coosos\IpFilterBundle\CoososIpFilterBundle::class => ['all' => true],
   ];
   

3. Create an IP Filter Model: Generate a Doctrine entity (e.g., IpFilter) with fields for ip, rangeStart, rangeEnd, isAuthorized, and environments (e.g., ['dev', 'test']). Example:

   php bin/console make:entity IpFilter
   

   Add fields:

   # src/Entity/IpFilter.php
   /**
    * @ORM\Column(type="string", length=45, nullable=true)
    */
   private $ip;
   
   /**
    * @ORM\Column(type="string", length=45, nullable=true)
    */
   private $rangeStart;
   
   /**
    * @ORM\Column(type="string", length=45, nullable=true)
    */
   private $rangeEnd;
   
   /**
    * @ORM\Column(type="boolean")
    */
   private $isAuthorized = false;
   
   /**
    * @ORM\Column(type="json")
    */
   private $environments = [];
   

4. Configure the Bundle: Add to config/packages/coosos_ip_filter.yaml:

   coosos_ip_filter:
       model: App\Entity\IpFilter
       firewall: main  # or your custom firewall name
   

5. First Use Case: Seed your database with allowed/blocked IPs (e.g., via a migration or doctrine:fixtures:load). Test access by simulating requests from different IPs:

   curl -H "X-Forwarded-For: 192.168.1.20" http://your-app.test/
   

Implementation Patterns

Workflows

1. Dynamic IP Filtering:

   • Use the bundle’s event listener (IpFilterListener) to check IPs on every request.
   • Example: Extend the listener to log blocked attempts:

     // src/EventListener/CustomIpFilterListener.php
     use Coosos\IpFilterBundle\EventListener\IpFilterListener;
     use Psr\Log\LoggerInterface;
     
     class CustomIpFilterListener extends IpFilterListener
     {
         private $logger;
     
         public function __construct(LoggerInterface $logger)
         {
             $this->logger = $logger;
         }
     
         protected function onBlockedRequest($ip)
         {
             $this->logger->warning(sprintf('Blocked IP: %s', $ip));
             parent::onBlockedRequest($ip);
         }
     }
     

   • Register the listener in services.yaml:

     services:
         App\EventListener\CustomIpFilterListener:
             arguments: ['@logger']
             tags:
                 - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }
     

2. Environment-Specific Rules:

   • Leverage the environments field to apply rules per environment (e.g., allow 192.168.1.* only in dev).
   • Example fixture for dev environment:

     // src/DataFixtures/IpFilterFixtures.php
     public function load(ObjectManager $manager)
     {
         $ipFilter = new IpFilter();
         $ipFilter->setRangeStart('192.168.1.0');
         $ipFilter->setRangeEnd('192.168.1.255');
         $ipFilter->setIsAuthorized(true);
         $ipFilter->setEnvironments(['dev']);
         $manager->persist($ipFilter);
         $manager->flush();
     }
     

3. Integration with Security System:

   • Combine with Symfony’s security component to deny access programmatically:

     // src/Security/Voter/IpFilterVoter.php
     use Coosos\IpFilterBundle\IpFilterManager;
     
     class IpFilterVoter extends Voter
     {
         private $ipFilterManager;
     
         public function __construct(IpFilterManager $ipFilterManager)
         {
             $this->ipFilterManager = $ipFilterManager;
         }
     
         protected function supports($attribute, $subject)
         {
             return $attribute === 'IP_FILTER';
         }
     
         protected function voteOnAttribute($attribute, $subject, TokenInterface $token)
         {
             $ip = $token->getClientIp();
             if (!$this->ipFilterManager->isIpAllowed($ip)) {
                 return AccessDeniedException::create();
             }
             return AccessDecision::GRANTED;
         }
     }
     

   • Register the voter in security.yaml:

     security:
         access_control:
             - { path: ^/, roles: ROLE_USER, voter: App\Security\Voter\IpFilterVoter, attribute: IP_FILTER }
     

4. Bulk IP Management:

   • Use Doctrine’s BulkOperations or a custom command to update IPs en masse:

     php bin/console make:command UpdateIpFilters
     

     Example command:

     // src/Command/UpdateIpFiltersCommand.php
     use Doctrine\ORM\EntityManagerInterface;
     use Coosos\IpFilterBundle\Entity\IpFilter;
     
     class UpdateIpFiltersCommand extends Command
     {
         protected static $defaultName = 'app:update-ip-filters';
     
         private $entityManager;
     
         public function __construct(EntityManagerInterface $entityManager)
         {
             $this->entityManager = $entityManager;
         }
     
         protected function execute(InputInterface $input, OutputInterface $output)
         {
             $ipFilters = $this->entityManager->getRepository(IpFilter::class)->findAll();
             foreach ($ipFilters as $ipFilter) {
                 $ipFilter->setEnvironments(['prod']); // Update all to 'prod'
                 $this->entityManager->persist($ipFilter);
             }
             $this->entityManager->flush();
             $output->writeln('Updated IP filters for all environments.');
         }
     }
     

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • The bundle checks IPs on every request, which can slow down high-traffic applications.
   • Mitigation:
     • Cache the IpFilterManager results if rules change infrequently:

       $cache = $container->get('cache.app');
       $key = 'ip_filter_rules_' . $_ENV['APP_ENV'];
       $rules = $cache->get($key, function() {
           return $this->ipFilterManager->getAllFilters();
       });
       

     • Use a reverse proxy (e.g., Nginx) for IP filtering where possible.

2. IP Detection Issues:

   • getClientIp() may return incorrect IPs behind proxies (e.g., X-Forwarded-For).
   • Fix: Configure Symfony’s trusted_proxies in framework.yaml:

     framework:
         trusted_proxies: ['127.0.0.1', '192.168.1.0/24']  # Add your proxy IPs
     

   • Override getClientIp() in the listener if needed:

     protected function getClientIp(Request $request)
     {
         return $request->headers->get('X-Forwarded-For') ?: $request->getClientIp();
     }
     

3. Priority Logic:

   • Authorized IPs override unauthorized ranges, but this can lead to unexpected behavior if not tested.
   • Test Case:

     // Test that 192.168.1.20 is allowed even if 192.168.1.10-100 is blocked
     $this->assertTrue($ipFilterManager->isIpAllowed('192.168.1.20'));
     

4. IPv6 Support:

   • The bundle supports IPv6, but range validation is stricter than IPv4.
   • Tip: Use full IPv6 notation (e.g., 2001:0db8::/32) for ranges.

5. Database Bloat:

   • Storing every IP range individually can bloat the database.
   • Optimization: Use CIDR notation (e.g., 192.168.1.0/24) and store as a single record.

Debugging

1. Enable Debugging:
   • Temporarily log IP checks in the listener:

     protected function isIpAllowed($ip)
     {
         $result = parent::isIpAllowed($ip);
         \Log::debug(sprintf('IP %s allowed: %s', $ip, $result));
         return $result;
     }
     

2