Epl Laravel Package

Getting Started

opensoft/epl is a small MIT-licensed Laravel helper package (last tagged release February 2016, ~10 stars) that predates package auto-discovery and the modern Laravel API surface. Treat it as a thin convenience layer over Eloquent queries and Blade-rendered HTML output rather than a framework of its own — the entire public API is small enough to read end-to-end in an afternoon.

Install it with an explicit constraint so a future tag can never surprise you:

composer require "opensoft/epl:^1.0" --prefer-dist
composer show opensoft/epl   # confirm the resolved version and its illuminate/* requirements

Because the last release is from the Laravel 5.2 era, you will almost certainly be running it on a legacy application. If your host project is on Laravel 8+, expect dependency conflicts against illuminate/support and illuminate/database; either install into the legacy app or vendor-copy the source into app/Support/Epl and namespace it yourself.

Where to look first, in order:

1. vendor/opensoft/epl/README.md — likely the only documentation, and probably a single usage example.
2. vendor/opensoft/epl/composer.json — tells you exactly which Laravel version the author targeted; this is the real "support matrix."
3. vendor/opensoft/epl/src/ — locate the primary entry class, the service provider, and any facade. That trio defines your whole integration surface.

Since auto-discovery landed in Laravel 5.5, register the provider and any facade manually in config/app.php:

'providers' => [
    OpenSoft\Epl\EplServiceProvider::class,
],
'aliases' => [
    'Epl' => OpenSoft\Epl\Facades\Epl::class,
],

The canonical first use case is an admin screen: take a filtered Eloquent query, hand it to the package, and render a table with column headers, sortable links, and pagination — the code you would otherwise write by hand in every controller.

Implementation Patterns

Keep definitions out of controllers. Create one small class per screen (e.g. app/Grids/UsersGrid.php) that declares the query, the column set, formatters, and allowed sort keys. The controller then reduces to three lines: build query, instantiate grid, return view. This is the difference between a maintainable admin panel and a wall of closures.

Formatter closures per column. Use closures for anything derived — status badges, formatted dates, links to related records — and return already-escaped values where possible so the view stays dumb. Push presentation logic down into the grid, not up into Blade.

Thin controller, fat grid, dumb view:

public function index(UsersGrid $grid)
{
    return view('admin.users.index', ['grid' => $grid->fromRequest(request())]);
}

{!! $grid->render() !!}

Whitelist sort and filter keys explicitly. Accept ?sort=created_at&dir=desc from the request only after matching against a hard-coded array of permitted column names. Never pass a raw request parameter into an ORDER BY or a whereRaw.

Let Eloquent paginate, don't re-implement it. Call ->paginate($perPage) on the query before handing it to the package, pass the resulting paginator through, and render {!! $paginator->appends(request()->query())->links() !!} in the view. This keeps page-size, query-string preservation, and the page parameter contract in Laravel's hands.

Eager-load everything a formatter touches. A closure that calls $row->organisation->name inside a loop over 50 rows is 50 extra queries. Add ->with('organisation') at the query level and verify with DB::listen() or Telescope while developing.

Test the data layer, not the HTML. Assertions against generated markup break on every cosmetic change. Test that your grid class returns the expected rows for a given request, and keep one smoke test that renders the view and asserts a 200.

Gotchas and Tips

• The package is effectively abandoned. No security patches since 2016. Pin exact or caret versions, commit composer.lock, and budget for a fork. If the codebase is still alive in two years you will be maintaining this file yourself.
• Legacy Laravel APIs. Code written for 5.2 may call lists(), pluck() with old signatures, array_get(), str_* helpers, or use curly-brace string offsets ($str{0}) — all removed or deprecated in PHP 7.4+/8.x. Run php -l and a static analyser over vendor/opensoft/epl/src before trusting it on PHP 8.
• Dynamic properties and nullable parameters in PHP 8.2+ will emit deprecations from this vintage of code. Suppress narrowly in the legacy app or patch the vendor copy — do not blanket-suppress project-wide.
• Raw HTML output. render() returns an HTML string, so {!! !!} is required. That also means any user-supplied value echoed into a cell must be escaped inside your formatter; the package will not do it for you.
• No config to publish. If config/ doesn't exist in the package, don't hunt for vendor:publish — settings are almost certainly constructor arguments or overridable properties on the base class. That is also your extension point: subclass the grid/table class and override the render or column-building methods rather than patching vendor files.
• Debugging render issues: dump $query->toSql() and $query->getBindings() first, then dd($grid->render()) to see whether the problem is the data or the markup. Most "empty table" reports are a missing SELECT column or a paginator mismatch, not a package bug.
• Check the paginator contract carefully if you upgrade Laravel: the LengthAwarePaginator interface has changed (notably the render() → links() rename in 5.3, and Illuminate\Contracts\Pagination\Paginator additions since). A package that type-hints the old contract will fatal on modern versions.
• When to abandon it: if you are starting greenfield, use a maintained alternative — Filament tables, spatie/laravel-query-builder plus a Blade component, or Laravel DataTables. This package earns its keep only in an existing 5.x codebase where the cost of rewriting every admin screen exceeds the cost of pinning a frozen dependency.