Getting Started

Larastrap is packaged in Packagist, the main PHP repository. You can install it within your Laravel application using Composer.

Then you probably want a configuration file, editable as you like, with a few default config and examples. To generate the config/larastrap.php file, run

Be aware you still have to install Bootstrap assets (both CSS and JS) in your page, with you preferred method (npm i bootstrap, deeplinking the CDN or whatever). It is suggested to use the laravel/ui package to start up your new application.

Larastrap is a collection of Blade Components, as defined by the Laravel's documentation.

Those can be used in any Blade template using the syntax

<x-larastrap::componentname />

or, for Containers

<x-larastrap::componentname>
    contents
</x-larastrap::componentname>

Each element accepts a variety of parameters, that can be passed inline using HTML attributes (whose name have to be prefixed with a : character when handling a PHP expression).

<x-larastrap::componentname id="a_static_string" :name="$a_php_variable" />

Parameters can also be massively passed through the params parameter, in a single array.

<x-larastrap::componentname :params="['id' => a_static_string, 'name' => $a_php_variable]" />

Remember that, as per native Blade Components' behavior, is also possible to dynamically invoke a component by his own name using the x-dynamic-component tag.

<x-dynamic-component :component="sprintf('larastrap::%s', $a_component_type)" :params="['id' => 'a_static_string', 'name' => $a_php_variable]" />

Check the documentation of each different element to discover more about his usage, the accepted parameters, the implicit features and behaviors and more!

The whole configuration of Larastrap is centered on the many possible parameters assignable to each element, each having his own meaning.

Parameters' values are evaluated accordingly to a given priority sequence:

• parameters defined inline within the element have the highest priority
• some parameter can be inherited by the parent Container
• then it is the turn for values got from the config/larastrap.php file
  • custom elements may have their own defaults, in the custom array
  • each base element may have his own defaults, within the elements array
  • basic default are to be written in the commons array
• finally, if no other value has been found, the defaults hard coded in the code are applied

This hierarchy permits a fine-grained configuration: a global one, intended to keep the whole behaviors coherent within the application, and the ability to specify each parameter only when required.

Given the following sample file:

<?php

return [
    'commons' => [
        'color' => 'danger',
    ],

    'elements' => [
        'button' => [
            'color' => 'success',
        ]
    ],

    'customs' => [
        'mybutton' => [
            'extends' => 'button',
            'params' => [
                'color' => 'warning',
            ]
        ]
    ],
];

All elements will have a default color = danger , apart for x-larastrap::button that will have color = success . When instead using the custom element x-larastrap::mybutton , even if it extends the base x-larastrap::button type, it will have color = warning .

The Larastrap's configuration file in your Laravel application permits to define the default behavior of each component: every parameter described in the documentation has his own internal defaults, but can be overwritten once to personalize each aspect of the final render.

Another parameter which can be found in the config/larastrap.php file is prefix, to be used to customize the Blade's prefix for Larastrap components (including your custom ones'). Mostly intended for lazy developers who want to avoid the default, long and boring x-larastrap formula (which, independently from the eventual custom prefix, works in any case).

<!--

return [
    'prefix' => 'ls',
];

-->

<x-ls::text name="test" label="Label" />

<div class="row mb-3">
  <label for="input-8dbb5cdf0fb32ef3e3647a6f66babbdf" class="col-4 col-form-label">Label</label>
  <div class="col-8">
    <input id="input-8dbb5cdf0fb32ef3e3647a6f66babbdf" type="text" class="form-control" name="test" value="">
  </div>
</div>

Most of the internal state of Larastrap is kept into the LarastrapStack service container, a singleton instantiated by Larastrap's Service Provider. It exposes a few utility function, including one to override the configuration usually get from the config/larastrap.php file.

<?php

$stack = app()->make('LarastrapStack');

/*
    From here, all forms have use the horizontal formview (despite what is
    written in the configuration file).
    The configuration of all other component types is left untouched.
*/
$stack->overrideNodesConfig([
    'form' => [
        'formview' => 'horizontal'
    ]
]);

/*
    Restores the configuration from the file
*/
$stack->overrideNodesConfig(null);