Sps Bundle Laravel Package

Getting Started

The bundle has one star, zero dependents, and its last release was February 2021 — so treat the README as a starting hypothesis, not documentation. Your first moves:

1. Install and inspect. composer require zk2/sps-bundle (check the README for the exact constraint; 2021 packages often predate Symfony 6, so you may need --with-all-dependencies and possibly a symfony/framework-bundle compatibility shim). Then open vendor/zk2/sps-bundle/ — the DependencyInjection/, Resources/config/, and Controller/ directories tell you more in five minutes than the README will.
2. Register the bundle in config/bundles.php if it isn't auto-discovered, and check for a Resources/config/services.yaml you need to import.
3. Find the extension point. Almost every "Search / Pagination / Sort" bundle exposes an abstract controller, a trait, or a service you configure with column definitions. Look for a class marked abstract in Controller/ or a service tagged for table rendering. That class is your base.
4. First use case: a single read-only admin index — e.g. a list of Orders with a search box, page links, and clickable column headers. Start there rather than wiring it into a complex multi-entity dashboard.

If the bundle provides Twig templates under Resources/views/, override them in templates/bundles/SPSBundle/ so you're not editing vendor code.

Implementation Patterns

Because the package is a thin SPS abstraction over Doctrine, expect the following shape in practice:

Subclass-the-controller pattern. Most likely you extend an abstract SPS controller and declare:

• the repository / query builder,
• the searchable fields,
• the sortable columns and their default direction,
• the page size.

Keep these declarations in one method per resource so you can spot drift when you add columns.

// Illustrative — verify against vendor source
class OrderController extends AbstractSPSController
{
    protected function configure(): void
    {
        $this->setQueryBuilder($this->em->getRepository(Order::class)->createQueryBuilder('o'));
        $this->setSearchable(['o.reference', 'o.customerName']);
        $this->setSortable(['o.createdAt' => 'desc', 'o.total' => 'asc']);
        $this->setPerPage(25);
    }
}

Search → Pagination → Sort pipeline. The bundle's whole value is composing these three: apply WHERE … LIKE from the search input, then setMaxResults/setFirstResult, then ORDER BY. When you add a custom filter (date range, status enum), inject it into the query builder before pagination is applied — otherwise your COUNT for the pager will be wrong.

Service-layer wrapping. Don't let the SPS config bleed across your controllers. Build a small TableQuery service per entity that takes a Request and returns a Paginator object, then keep the SPS controller a thin adapter. This makes the bundle easy to swap out if it goes unmaintained (which, given the release date, is a real risk).

Twig integration. If the bundle ships a table/pager template, use it for admin screens and override only the CSS classes. Keep your own pagination markup for user-facing pages — you'll want control over the markup and rel/canonical logic.

Sort whitelisting. Always whitelist sortable columns against the config; never pass the sort query parameter straight into addOrderBy (SQL injection and unindexed-sort DoS). The bundle likely does this for you, but verify addOrderBy is only called with declared fields.

Gotchas and Tips

• It's a Symfony bundle, not a Laravel package. There's no service provider, no facade — if you're coming from Laravel, the mental model is "bundle config + container services + Twig", not "manager class + helpers". Register it in config/bundles.php and wire services in config/services.yaml.
• Symfony version drift. A 2021 release predates Symfony 6's Attribute autoconfiguration and the FrameworkBundle route-loader changes. Check composer.json in the vendor dir for symfony/* constraints; you may need symfony/framework-bundle:^5.4 or a ContainerBuilder compatibility patch.
• Count queries double-fire. Most SPS bundles run the main query for results and a separate COUNT(*) for the pager. If you join relations for search, the count returns inflated totals — use ->select('COUNT(DISTINCT o.id)') or set ->distinct() explicitly in your configure() after the joins.
• State in the URL, not the session. Search + page + sort should live entirely in the query string so links are shareable and the back button works. If the bundle stores state in session by default, override it — session-backed pagination is a debugging nightmare and breaks browser history.
• Default sort must be deterministic. Always append a secondary sort on the primary key (->addOrderBy('o.id', 'ASC')). Without it, rows shuffle between pages when the primary sort column has ties — a classic "why is this row on page 2 and page 3?" bug.
• Empty search vs. null search. Check how the bundle treats an empty q= parameter: it should be a no-op (LIKE '%%' on a large table is a full scan even when it "matches everything"). Guard with if ($q !== null && $q !== '') in your query-building code.
• Extension points to prefer when modifying behavior: override the abstract controller's query-builder hook, override the Twig template, or decorate the SPS service — in that order. Don't fork the bundle; a 1-star package won't upstream your patch.
• Maintenance reality check. With one star, no dependents, and a two-year-old last release, budget a half-day to read the source and write a small abstraction layer around it (see Service-layer wrapping above). Treat the bundle as a reference implementation of Search-Pagination-Sort, not as a long-term dependency. If the abstraction surface gets large enough, replacing it with a hand-rolled Paginator + Doctrine\ORM\Tools\Pagination\Paginator is usually cheaper than maintaining a fork.