rollerworks / pdb-symfony-bridge
PHP domain-parser Bridge for Symfony Cache, HTTP Client and FrameworkBundle (optional)
Requires
- php: ^8.1
- jeremykendall/php-domain-parser: ^6.3
- psr/simple-cache: ^1.0 || ^3.0
- symfony/cache: ^6.3 || ^7.0
Requires (Dev)
- matthiasnoback/symfony-dependency-injection-test: ^4.3
- nyholm/symfony-bundle-test: ^2.0
- phpunit/phpunit: ^9.6.13
- rollerscapes/standards: ^1.0
- symfony/console: ^6.3
- symfony/framework-bundle: ^6.3 || ^7.0
- symfony/http-client: ^6.3 || ^7.0
- symfony/phpunit-bridge: ^6.3 || ^7.0
Suggests
- rollerworks/pdb-validator: PHP domain-parser Constraints for Symfony Validator component
Conflicts
- symfony/framework-bundle: <6.0
This package is auto-updated.
Last update: 2024-10-30 02:16:28 UTC
README
This package provides a Symfony specific bridge for the PHP domain-parser by Jeremy Kendall and Ignace Nyamagana Butera.
Providing a Cache adapter, HTTP Client adapter, and optional FrameworkBundle
integration at Rollerworks\Component\PdbSfBridge\Bundle\RollerworksPdbBundle
.
Installation
To install this package, add rollerworks/pdb-symfony-bridge
to your composer.json:
$ php composer.phar require rollerworks/pdb-symfony-bridge
Now, Composer will automatically download all required files, and install them for you.
Symfony Flex (with contrib) is assumed to enable the Bundle and add required configuration. https://symfony.com/doc/current/bundles.html
Otherwise add the following configuration:
rollerworks_pdb: cache_pool: 'rollerworks.cache.public_prefix_db' #manager: http # either: 'http' (default), 'static' (requires manual updates) or 'mock' framework: cache: pools: # This name can be changed by setting `rollerworks_pdb.cache_pool` (**Don't reuse an existing cache pool!**) rollerworks.cache.public_prefix_db: adapter: cache.adapter.array # use a persistent adapter that can be easily invalidated like cache.adapter.memcached or cache.adapter.pdo default_lifetime: 604800 # one week, the cache should be automatically refreshed, unless manager=static is used
Requirements
You need at least PHP 8.1, and internet access is recommended but not required.
The public-suffix and top-level domain needs to manually updated from time to time. When internet access is available the PdbManager will automatically download the list and store it in the cache.
If no internet access is available, the local cache needs to refreshed manually. (Current not supported yet).
Basic Usage
Use the HttpUpdatedPdpManager
to get a PdbManager which automatically updates
the local cache using the HttpClient.
<?php use Rollerworks\Component\PdbSfBridge\HttpUpdatedPdpManager; use Symfony\Component\Cache\Psr16Cache(; // Any PSR16 Compatible adapter can be used, but it's recommended to use // A caching adapter that allows easy invalidation (like Pdo or Memcache). $cacheAdapter = ...; $cache = new Psr16Cache($cacheAdapter); // Optional, if not provided created as shown // $httpClient = new \Symfony\Component\HttpClient\HttpClient::create(); $manager = HttpUpdatedPdpManager::create($cache, /*$httpClient*/); // Not required. But recommended to warm-up the caches. $manager->updateCaches(); // \Pdp\PublicSuffixList $publicSuffixList = $manager->getPublicSuffixList(); // \Pdp\PublicSuffixList $topLevelDomainList = $manager->getTopLevelDomainList();
When internet access is not possible use the StaticPdpManager
instead.
<?php use Rollerworks\Component\PdbSfBridge\StaticPdpManager; // Any PSR16 Compatible adapter can be used, but it's recommended to use // A caching adapter that allows easy invalidation (like Pdo or Memcache). $cacheAdapter = ...; $cache = new Psr16Cache($cacheAdapter); // Provide the lists as described, realpath (not contents are string) $publicSuffixList = ...; // File provided from https://publicsuffix.org/list/public_suffix_list.dat $topLevelDomainList ...; // File provided from https://data.iana.org/TLD/tlds-alpha-by-domain.txt $manager = new StaticPdpManager($publicSuffixList, $topLevelDomainList, $cache); // Not required. But recommended to warm-up the caches. $manager->updateCaches(); // \Pdp\PublicSuffixList $publicSuffixList = $manager->getPublicSuffixList(); // \Pdp\PublicSuffixList $topLevelDomainList = $manager->getTopLevelDomainList();
For resolving domain names see the official documentation of [PHP domain-parser].
Testing
For using the manager in tests use
\Rollerworks\Component\PdbSfBridge\PdpMockProvider::getPdpManager()
.
Bundle Usage
First add set a suitable cache adapter (the Flex recipe uses ArrayCache
to allow
booting-up the Kernel, but for production usage it's required to use a persistent
cache adapter, as otherwise whenever the Manager is initialized the rules need to
be downloaded, parsed and cached).
# config/packages/rollerworks_pdb.yaml rollerworks_pdb: cache_pool: 'rollerworks.cache.public_prefix_db' framework: cache: pools: # This name can be changed by setting `rollerworks_pdb.cache_pool` (**Don't reuse an existing cache pool!**) rollerworks.cache.public_prefix_db: adapter: cache.adapter.memcached # or cache.adapter.pdo default_lifetime: 604800 # one week, the cache should be automatically refreshed
Offline usage
When the HttpClient component is installed and enabled the HttpUpdatedPdpManager
is automatically used. When the HttpClient is not available the StaticPdpManager
is used instead.
To force usage of the static adapter set configuration rollerworks_pdb.manager
to static
.
When the static adapter is enabled you must run rollerworks-pdb:update
with
the lists provided as files names.
And disable expiration of the cache, as otherwise the pre-bundled version will be used instead.
First download the lists from https://publicsuffix.org/list/public_suffix_list.dat and https://data.iana.org/TLD/tlds-alpha-by-domain.txt respectively.
And load them into the cache.
$ bin/console rollerworks-pdb:update public_suffix_list.dat tlds-alpha-by-domain.txt
The files path can be either absolute or relative to the current working directory.
Cache expiration disable: Symfony cache-warming is designed as such that once the cache is warmed-up no future file writing is expected (for security reasons).
Which is why the cache should be easily updatable, with preferable no filesystem writing.
The rollerworks-pdb:update
updates the cache without writing the provided files
to the application var/cache directory. So when the cache does expire, there would
be no files to read from, to prevent this the pre-bundled lists (used for the MockManager
)
are used instead, but these are only updated from time to time, and thus outdated.
Versioning
For transparency and insight into the release cycle, and for striving to maintain backward compatibility, this package is maintained under the Semantic Versioning guidelines as much as possible.
Releases will be numbered with the following format:
<major>.<minor>.<patch>
And constructed with the following guidelines:
- Breaking backward compatibility bumps the major (and resets the minor and patch)
- New additions without breaking backward compatibility bumps the minor (and resets the patch)
- Bug fixes and misc changes bumps the patch
For more information on SemVer, please visit http://semver.org/.
License
This library is released under the MIT license.
Contributing
This is an open source project. If you'd like to contribute, please read the Contributing Guidelines. If you're submitting a pull request, please follow the guidelines in the Submitting a Patch section.