{"id":24764081,"url":"https://github.com/stillat/blade-directives","last_synced_at":"2025-07-13T17:05:47.607Z","repository":{"id":46347467,"uuid":"420533397","full_name":"Stillat/blade-directives","owner":"Stillat","description":"A package that makes writing Laravel Blade directives easier when requiring multiple parameters.","archived":false,"fork":false,"pushed_at":"2023-02-01T14:44:59.000Z","size":18,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-13T17:02:20.630Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Stillat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"JohnathonKoster"}},"created_at":"2021-10-23T22:09:22.000Z","updated_at":"2025-07-09T14:09:00.000Z","dependencies_parsed_at":"2023-02-17T06:30:58.727Z","dependency_job_id":null,"html_url":"https://github.com/Stillat/blade-directives","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Stillat/blade-directives","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fblade-directives","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fblade-directives/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fblade-directives/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fblade-directives/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stillat","download_url":"https://codeload.github.com/Stillat/blade-directives/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fblade-directives/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265175560,"owners_count":23722659,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-28T21:32:32.473Z","updated_at":"2025-07-13T17:05:47.549Z","avatar_url":"https://github.com/Stillat.png","language":"PHP","funding_links":["https://github.com/sponsors/JohnathonKoster"],"categories":[],"sub_categories":[],"readme":"# Blade Directives\n\nThis library provides utility methods that aim to make writing Laravel Blade directives easier, especially when attempting to use multiple parameters.\n\nThis library makes it possible to write code like this:\n\n```php\n\u003c?php\n\nuse Stillat\\BladeDirectives\\Support\\Facades\\Directive;\nuse Illuminate\\Support\\Str;\n\nDirective::callback('limit', function ($value, $limit = 100, $end = '...') {\n    return Str::limit($value, $limit, $end);\n});\n```\n\nWhich allows you or your directive's users to write Blade templates like this:\n\n```blade\n{{-- Invoke our directive callback with default arguments --}}\n@limit($myString)\n\n{{-- Invoke our directive callback and specify a limit --}}\n@limit($myString, 50)\n\n{{-- Invoke our directive callback and change only the \"end\" parameter using named arguments --}}\n@limit($myString, end: '---')\n\n{{-- Invoke our directive callback with all parameters --}}\n@limit($myString, 5, 'the cap')\n\n{{-- Invoke our directive callback with all parameters using named arguments --}}\n@limit($myString, end: ':o', limit: 5)\n```\n\nNote that we did not have to return a string, or do any string manipulation when using the `callback` method. When\nusing the `callback` method, Blade Directives will do the heavy lifting behind the scenes for you, and you can\njust write Blade directives like any other PHP method.\n\n## Compilation Methods\n\nThe most basic way to use the `compile` method is like so:\n\n```php\n\u003c?php\n\nuse Stillat\\BladeDirectives\\Support\\Facades\\Directive;\n\nDirective::compile('slugify', function ($value, $separator = '-') {\n    return '\u003c?php echo \\Illuminate\\Support\\Str::slug($value, $separator); ?\u003e';\n});\n```\n\nWhich allows your users to write Blade like this:\n\n```blade\n@slugify($title)\n@slugify($title, '_')\n```\n\nDevelopers using directives written using the `compile` method can also use named arguments:\n\n```php\n\u003c?php\n\nuse Stillat\\BladeDirectives\\Support\\Facades\\Directive;\n\nDirective::compile('limit', function ($value, $limit = 100, $end = '...') {\n   return '\u003c?php echo \\Illuminate\\Support\\Str::limit($value, $limit, $end); ?\u003e';\n});\n```\n\n```blade\n@limit($myString, end: '---')\n@limit($myString, end: ':o', limit: 5)\n```\n\nThat just feels better, and we didn't have to resort to error-prone `explode` calls, or `json_encode/json_decode`.\n\n## Installation\n\nThis library can be installed with Composer:\n\n```\ncomposer require stillat/blade-directives\n```\n\n## Writing Directives\n\nTo get started, add the following import to the top of your PHP file:\n\n```php\nuse Stillat\\BladeDirectives\\Support\\Facades\\Directive;\n```\n\nThe `Directive` façade provides three different methods that you can choose from depending on what you require for a given situation:\n\n* `params($name, callable $handler)` - registers a new Blade directive similarly to Blade's default `directive` method. You will have access to the parameters within the callback through `$this-\u003eparameters`. You will only receive the raw input string as the first, and only argument.\n* `make($name, callable $handler)` - registers a new Blade directive with support for multiple parameters\n* `compile($name, callable $handler)` - registers a new Blade directive with support for multiple parameters. This method allows you to return a PHP string, which will have variables replaced for you automatically\n\n### Using the `make($name, callable $handler)` Method\n\nThe `make` method allows you to specify (and receive) multiple parameters on your directive's callback. You are still responsible for manually constructing the final PHP string for the Blade compiler:\n\n```php\n\u003c?php\n\nuse Stillat\\BladeDirectives\\Support\\Facades\\Directive;\n\nDirective::make('greet', function ($name, $age) {\n   return '\u003c?php echo \"Hello, \".'.$name.\". ' - '. \".$age.\"; ?\u003e\";\n});\n```\n\nThe following Blade:\n\n```blade\n@greet('Hello!', 32)\n@greet($varName, $ageVar)\n@greet(' Escaped \\' string!', '32')\n```\n\nProduces the following compiled output:\n\n```php\n\u003c?php echo \"Hello, \".'Hello!'. ' - '. 32; ?\u003e\n\u003c?php echo \"Hello, \".$varName. ' - '. $ageVar; ?\u003e\n\u003c?php echo \"Hello, \".' Escaped \\' string!'. ' - '. '32'; ?\u003e\n```\n\n### Using the `compile($name, callable $handler)` Method\n\nThe `compile` method allows you to return a PHP string as the result of your directive's handler. The internal compiler will work to replace the variable references with the required compiled output, which makes it much easier for you to write your directive.\n\nLet's rewrite the `greet` directive using the `compile` method:\n\n```php\n\u003c?php\n\nuse Stillat\\BladeDirectives\\Support\\Facades\\Directive;\n\nDirective::compile('greet', function ($name, $age) {\n   return '\u003c?php echo \"Hello, $name - $age\" ?\u003e';\n});\n```\n\nThe following example demonstrates using default values for directive parameters:\n\n```php\n\u003c?php\n\nuse Illuminate\\Support\\Facades\\Blade;\nuse Stillat\\BladeDirectives\\Support\\Facades\\Directive;\n\nDirective::compile('test', function ($data = [1, 2, 3]) {\n   return '\u003c?php foreach ($data as $value): ?\u003e';\n});\n\nBlade::directive('endtest', function () {\n    return '\u003c?php endforeach; ?\u003e';\n});\n```\n\nThe following Blade:\n\n```blade\n@test(['one', 'two', 'three'])\n\n@endtest\n```\n\nProduces compiled output similar to the following:\n\n```php\n\u003c?php foreach (((['one', 'two', 'three']) ?? (array (\n  0 =\u003e 1,\n  1 =\u003e 2,\n  2 =\u003e 3,\n))) as $value): ?\u003e\n\n\u003c?php endforeach; ?\u003e\n```\n\nIf the user did not supply any values like so:\n\n```blade\n@test\n\n@endtest\n```\n\nThe compiled output would change to:\n\n```php\n\u003c?php foreach (((null) ?? (array (\n  0 =\u003e 1,\n  1 =\u003e 2,\n  2 =\u003e 3,\n))) as $value): ?\u003e\n\n\u003c?php endforeach; ?\u003e\n```\n\n## Escaping Variable Names\n\nThis section applies to the `compile` method.\n\nThe \"compiler\" is effectively a glorified \"find and replace\", and can make it difficult to use a variable name if it also matches one of your parameter names. To escape a variable name, precede it with the `\\` character:\n\n```php\n\u003c?php\n\nuse Stillat\\BladeDirectives\\Support\\Facades\\Directive;\n\nDirective::compile('escapeTest', function ($test, $anotherVar) {\n   return '\u003c?php echo 5 + ($test) / $anotherVar; ?\u003e \\$test \\$anotherVar $anotherVar';\n});\n```\n\nThe following Blade:\n\n```blade\n@escapeTest(5 + 3 * 2, 15)\n```\n\nProduces compiled output similar to the following:\n\n```php\n\u003c?php echo 5 + (5 + 3 * 2) / 15; ?\u003e $test $anotherVar 15\n```\n\nAs you can see, anything that matches a variable name preceded by the `\\` character is escaped for you. Additionally, all occurrences of the variable are replaced in the string, not just within PHP areas.\n\n## Issues\n\nDue to the nature of projects like this, it is guaranteed that it will break in interesting ways. When submitting issues, please include as much information as possible to help reproduce the issue, and a clear explanation of desired behavior.\n\n## License\n\nMIT License. See LICENSE.MD\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstillat%2Fblade-directives","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstillat%2Fblade-directives","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstillat%2Fblade-directives/lists"}