Pagerfanta Package Structure Updates
Today version 2.4 of Pagerfanta and 2.5 of BabDevPagerfantaBundle were released, including large changes in how each of the packages are structured and marks a shift in the recommended usage of the library and Symfony bundle.
The two main changes in the Pagerfanta library are:
- Moving features from the Symfony bundle to the core library
- Separating the library into several smaller packages maintained from the core monorepo
Moved Features From Bundle To Library
The Symfony bundle previously contained the Twig integration for Pagerfanta, as well as an API for building and using routing related features when rendering a
Pagerfanta instance. Given Twig's use with the wider PHP ecosystem, it made sense to "promote" the Twig integration from only being available when using Pagerfanta within Symfony to being a core feature of the Pagerfanta library itself. This also moved the route generator interfaces from the bundle to the library (as these were introduced to extract the routing logic from being inside the Twig classes themselves). The bundle classes and interfaces are still present, however are deprecated with the new release and are removed in 3.0 in favor of their counterparts from the library.
Historically, Pagerfanta has existed as a monorepo with all of the features of the library. As of the 2.4 release, this includes the core Pagerfanta class itself, the route generator API, the View API and its two implementations (PHP classes and Twig), and adapters providing support for 11 PHP packages. However, because of the optional nature of most of these integrations, there are no explicit requirements to any of the external packages resulting in de facto unbounded version constraints and a wide support range and in the case of the monolithic
pagerfanta/pagerfanta package it results in conflicts that makes it difficult to fully test all package versions that are claimed to be supported. Therefore, to better enforce that the dependency chain can be resolved to a set of supported versions, it is now recommended that users of the library install the separate packages that they depend on instead of relying on the monolithic
pagerfanta/pagerfanta package. All of these packages are created using a git subsplit workflow (similar to how Laravel, Sylius, and Symfony split their many packages from a central monorepo to separate repos) and the monolithic package will continue to always be usable.
Separate packages are available on Packagist for the following features:
- Core API (Pagerfanta class, route generators, PHP views/templates, and adapters that don't use an external connection)
- Doctrine Collections Adapters
- Doctrine DBAL Adapters
- Doctrine MongoDB Adapter
- Doctrine ORM Adapter
- Doctrine PHPCR ODM Adapter
- Elastica Adapter
- Solarium Adapter
- Twig integration
Note, separate packages were not created for the deprecated Mandango,
ext/mongo, and Propel adapters.
In the Symfony bundle's 3.0 release, the package will change from relying on the monorepo to only installing the
pagerfanta/twig packages and users will need to install the packages for any adapters as necessary.
Other changes in these releases include:
PagerfantaInterfaceis no longer deprecated, dating back to the original library's 1.0 release it was marked as deprecated and has historically been an empty interface; the deprecation has been removed and in the 3.0 release the interface will be properly filled in
- Inside the Symfony bundle, a
referenceTypeoption was added to specify the
$referenceTypeparameter when calling
UrlGeneratorInterface::generate(), this can allow you to output absolute URLs if desired (useful in an API context)