Visma Business Connect Laravel Package

Getting Started

1. Install the package with Composer using the package’s documented name, then publish any config if the package exposes it:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package-config>
   

2. Look first at the package’s filter definition/registration point — typically a config file, a model trait, or a dedicated filter class. This is where allowed filters and aliases are declared.
3. Apply the filter to an Eloquent query in a controller or form request:

   $posts = Post::query()
       ->filter($request->only(['status', 'author', 'search']))
       ->paginate();
   

4. First use case: an index endpoint with a search box and a status dropdown. Start with simple filters, then use the new v2.1.0 parenthesis support when a user needs “match this OR that, AND still apply the other filters”:

   ?filter=(status=active OR status=pending)&author=42
   

   This lets you group related conditions without writing custom query scopes for every combination.

Implementation Patterns

• Start flat, then group. Implement simple filters first (status, author_id, created_after). Add parentheses only where precedence matters, e.g. (status=active OR status=pending) AND author_id=42.
• Use grouping for search. A common pattern is to group multiple LIKE conditions:

  ?filter=(title~=laravel OR body~=laravel)&published=1
  

  This keeps the search term scoped to the text fields while other filters remain ANDed.
• Compose groups with other filters. Treat parentheses as a precedence tool, not a separate filtering system. Keep global filters outside the group so pagination, tenancy, and authorization scopes still apply.
• Prefer validated input over raw query strings. Map request parameters to a whitelist of filter keys in a form request or dedicated filter object. This is especially important once groups are allowed, because nested input expands the possible query surface.
• Reuse filter definitions. Define aliases and allowed operators once, then reuse them across endpoints. Avoid duplicating grouping logic in controllers.
• Integrate with existing scopes. Apply package filters before or after local scopes consistently. For example, apply tenant scoping first, then user-driven filters, so grouped filters cannot escape tenant boundaries.
• Test the generated SQL. For grouped filters, assert both results and SQL shape. A feature that changes precedence is easy to get subtly wrong.
• Use parentheses sparingly in public APIs. If your API exposes raw filter expressions, document the grouping syntax and validate nesting depth. For internal/admin endpoints, grouped filters are usually safe and very useful.

Gotchas and Tips

• Parentheses change precedence, not evaluation order. A grouped OR can still be combined with outer AND conditions in ways users do not expect. Always test mixed expressions such as (a OR b) AND c versus a OR (b AND c).
• Empty groups are dangerous. () or a group containing only ignored filters can produce invalid SQL or silently drop conditions. Validate that groups contain at least one allowed filter.
• URL encoding matters. Parentheses are legal in query strings but some HTTP clients and proxies encode or strip them. Test with your actual frontend/HTTP client, and document whether users should send ( / ) literally or encoded.
• Whitelist aggressively. Grouping support makes it easier to accidentally expose arbitrary column names or operators. Reject unknown filter keys and unsupported operators before the query builder sees them.
• Watch nesting limits. Deeply nested groups can produce hard-to-debug SQL and performance issues. Enforce a maximum depth if the package allows recursive groups.
• Debug with SQL and bindings. When a grouped filter behaves unexpectedly, dump toSql() and getBindings() rather than only inspecting the result set. This quickly reveals missing parentheses or misassociated conditions.
• Check config for delimiters and aliases. Parenthesis syntax may depend on configured delimiters or operator aliases. If grouping does not work, verify the config was published and cached config was cleared (php artisan config:clear).
• Extension point: custom filters. If the built-in operators are insufficient, implement a custom filter class or query scope and register it through the package’s extension mechanism rather than bypassing the filter layer.
• Upgrade note for v2.1.0. This release is additive — parenthesis support around filters. Existing flat filter syntax should continue to work, but re-run filter-related tests after upgrading, especially tests that assert exact SQL strings.
• Document examples for consumers. Because grouping syntax is easy to misuse, include concrete examples in your API docs: simple filter, grouped OR, grouped OR with outer AND, and an invalid/empty group example.