Ace Bundle Laravel Package

Getting Started

1. Install the bundle

composer require ns/ace-bundle

Because the package has very low adoption (1 star, no dependents), check the composer.json of the tag you install to confirm which Symfony versions it declares support for before you commit to a version constraint. Expect an older constraint (Symfony 2.x/3.x era) and pin it explicitly:

"ns/ace-bundle": "^1.0"

2. Register it

// config/bundles.php
return [
    // ...
    Ns\AceBundle\AceBundle::class => ['all' => true],
];

If the bundle predates Symfony Flex, the class name may be different — read composer.json's autoload.psr-4 map first.

3. Publish the assets

The point of this bundle is to ship the Ace admin template's CSS/JS/fonts. Run:

php bin/console assets:install --symlink

Then verify the files landed under public/bundles/ace/ (or web/bundles/ace/ on legacy apps). The exact directory is determined by the bundle name in the DI extension — check DependencyInjection/AceExtension.php for the alias.

4. Where to look first

In priority order:

1. Resources/views/ — the base layout Twig template(s). This is the actual deliverable of the package; everything else is plumbing.
2. README.md — for the documented block names and the required {% extends %} target.
3. DependencyInjection/Configuration.php — reveals what is actually configurable (usually very little).
4. Resources/public/ — confirms which Ace/Bootstrap/jQuery versions are vendored.

5. First use case

Create a page template that extends the bundle's layout:

{# templates/admin/dashboard.html.twig #}
{% extends '@Ace/layout.html.twig' %}

{% block content %}
    <h1>Dashboard</h1>
{% endblock %}

Render it from a controller and confirm the Ace chrome (sidebar, navbar, breadcrumbs) appears. That single render proves asset installation, bundle registration, and template resolution all work — do it before touching anything else.

Implementation Patterns

Layering your own base layout over the bundle's

Do not extend the bundle layout from every page. Insert one application-level layout in between:

{# templates/base_admin.html.twig #}
{% extends '@Ace/layout.html.twig' %}

{% block navbar %}
    {{ parent() }}
    <span class="label label-info">{{ app.user.username }}</span>
{% endblock %}

Every page then extends base_admin.html.twig. This gives you one file to edit when you need to replace or abandon the bundle later — a realistic concern given its maintenance status.

Overriding bundle templates without forking

Use the standard override path so you never patch vendor/:

templates/bundles/AceBundle/layout.html.twig

Copy the original there and modify. Symfony's template resolution picks this up automatically. For asset-level changes (theme colours, custom CSS) prefer appending your own stylesheet in a block rather than editing vendored SCSS — Ace's stylesheets are pre-built.

Sidebar and menu composition

Ace's signature feature is the collapsible sidebar. Rather than hardcoding menu items in the layout, define a block and populate it per-section:

{% block sidebar_menu %}
    {{ knp_menu_render('main', {'template': '@Ace/Menu/knp_menu.html.twig'}) }}
{% endblock %}

If the bundle ships menu partials, reuse them; if not, the Ace markup for nested <ul class="nav nav-list"> is the contract you need to match.

Form theming

If the bundle registers a form theme (check Resources/config/ for form_themes), enable it globally and stop hand-writing Bootstrap 3 form markup:

# config/packages/twig.yaml
twig:
    form_themes:
        - '@Ace/form/fields.html.twig'

Verify the block names in that file before relying on it — form themes are the most likely part to be stale against your Symfony version.

Asset pipeline integration

Legacy bundles assume Assetic. In a modern app, bypass it: reference bundles/ace/... paths directly from asset() or import Ace's CSS at the top of your Encore entrypoint. Mixing Assetic and Encore produces silent 404s on fonts, because Ace's CSS uses relative ../fonts/ URLs.

Wrapping it behind a feature flag if adoption is uncertain

Given the score here, treat the bundle as a UI skin, not architecture. Keep controllers rendering plain templates and let only the top-level layout know about Ace. Migrating to a hand-rolled Bootstrap 3 layout later then becomes a one-file change.

Gotchas and Tips

This package is effectively unmaintained. One star, zero dependents. Assume no security patches and no Symfony 5/6/7 compatibility work. Budget for vendoring a fork ("repositories": [{"type": "vcs", ...}]) or reimplementing the layout, and put that decision in writing before the UI grows on top of it.

Bootstrap 3 / jQuery coupling. Ace is built on Bootstrap 3 and an older jQuery. Dropping Bootstrap 4/5 components into these pages will break grid and panel classes silently — no errors, just wrong layout. Keep app-specific UI on Bootstrap 3 classes or isolate it.

Blank page with no error. Almost always template resolution, not PHP. Diagnose with:

php bin/console debug:twig | grep -i ace
php bin/console lint:twig templates/

debug:twig shows the resolved @Ace namespace path; if it's missing, the bundle name in config/bundles.php is wrong.

Missing icons and fonts after assets:install. Ace references icon fonts by relative path. Confirm the whole directory tree copied, not just css/ and js/. If you serve assets through Encore or a CDN, override the @font-face src URLs — the relative paths will not resolve.

Cache is aggressive here. After editing an override template or reinstalling assets on a legacy app, run rm -rf var/cache/* rather than just cache:clear, and hard-refresh the browser. Stale asset symlinks are the most common "my CSS change did nothing" cause.

Configuration is probably empty. Inspect Configuration.php before assuming YAML options exist. Most bundles of this type expose nothing beyond maybe enabled; writing config keys that aren't in the tree throws a InvalidConfigurationException at container compile time.

Extension points are limited to three things: Twig overrides, bundle inheritance (a subclass with getParent() returning AceBundle), and asset replacement. There is no event or service to hook into. Plan customisation accordingly — do not expect to swap the layout class or inject behaviour.

Check the Twig block names before extending. Undocumented or renamed blocks fail quietly by rendering the parent content. Read the layout file directly and list its blocks:

grep -n "{% block" vendor/ns/ace-bundle/Resources/views/layout.html.twig

Watch for hardcoded routes and helpers. Older bundles commonly reference app.request.attributes, path('fos_user_...'), or Assetic tags in templates. Grep the layout for path(, asset(, and assetic on day one; each match is an integration task.

No tests, no CI. Anything you rely on, add a smoke test for: a kernel test that renders one page extending the layout. That single test catches Symfony-version upgrades breaking template resolution long before users do.