Downloads
Stars
Version
IMPORTANT: this package is in its early stages and is not widely tested against all supported versions of PHP or Laravel. Please, use with caution...
Blade templates are great, but lacks a good way to define the variables it requires to work. In a normal template you must check if variables are set and/or set a default value for it.
Take this example:
<?php
if(!isset($type))
{
$type = 'boxed';
}
?>
<div class="component component-{{ $type }}">
@if($type == 'big')
<h1 class="component-title">{{ $object->title }}</h1>
@endif
<div class="component-content component-content-{{ $size ?? 'medium' }}">
{{ $object->content }}
</h1>
</div>
You must check if some variables are defined and set default values for some others. A colleague who has not worked with this template might ask:
$object
instance?$object
is not an instance of the right class?In big templates with lots of complex HTML code mixed with CSS framework classes and JS framework attributes, guessing
this information can be quite difficult. To solve these problems, this package adds a simple @expects
directive to
define the variables expected by the view.
@expects(\App\Object $object, string $type, string $size = 'medium')
<div class="component component-{{ $type ?: 'embedded' }}">
@if($type == 'big')
<h1 class="component-title">{{ $object->title }}</h1>
@endif
<div class="component-content component-content-{{ $size' }}">
{{ $object->content }}
</h1>
</div>
Using it as a wrapper for a phpDoc block does the same and allows IDEs like phpStorm to type-hint the variables:
@expects
/**
* Let's define the variables and its types
*
* @var \App\Object $object Object description
* @var string|null $type Type description
* @var string $size Size description (default: medium)
*/
@endexpects
<div class="component component-{{ $type ?: 'embedded' }}">
@if($type == 'big')
<h1 class="component-title">{{ $object->title }}</h1>
@endif
<div class="component-content component-content-{{ $size' }}">
{{ $object->content }}
</h1>
</div>
Both ways force $object
to be defined as a \App\Object
instance, $type
as a string and $size
will take the
medium value if not set.
The directive can be called using multiline syntax to improve legibility:
@expects(
\Very\Very\Very\Long\Namespace\Classes\FirstClass $class1,
\Very\Very\Very\Long\Namespace\Classes\SecondClass $class2,
\Very\Very\Very\Long\Namespace\Classes\ThirdClass $class3
)
The goal is that any programmer who works with the template knows immediately which variables are necessary for its operation, its types and default values.
You may also need to disable PHP tags in templates. This will prevent control structures from being used or variables from being declared, forcing the use of Blade directives for everything the template should do.
To do this just set the BLADE_EXPECTS_PHP_TAGS
environment variable to true
and and exception will be thrown if
<?php
or <?=
tags are detected.
The directive is parsed in two ways:
The resulting definition tells what to do:
This is translated in simple PHP conditionals placed in the compiled template.
Exceptions thrown are:
\Vaites\Laravel\BladeExpects\Exceptions\PhpTagsNotAllowedException
\Vaites\Laravel\BladeExpects\Exceptions\UndefinedVariableException
\Vaites\Laravel\BladeExpects\Exceptions\WrongTypeException
\Vaites\Laravel\BladeExpects\Exceptions\WrongClassException
All variables inherit from \Vaites\Laravel\BladeExpects\Exceptions\Exception
that inherits from
InvalidArgumentException
.
Just install using composer
and Laravel will load it automagically:
composer require vaites/laravel-blade-expects
If you don't want to use the package auto-discovery
you will need to add this to the service providers in config/app.php
:
'providers' => [
// ...
\Vaites\Laravel\BladeExpects\BladeExpectsServiceProvider::class,
]
The following environment variables can be defined:
BLADE_EXPECTS_ENABLED
: boolean, enable or disable the directive (tags are stripped)BLADE_EXPECTS_PHP_TAGS
: boolean, enable or disable the use of PHP tagsThe PhpStorm IDE can recognize the custom Blade directive if is set in File > Settings > Languages & Frameworks > PHP > Blade > Directives by adding a new one with the following properties: