ShortDB
A PHP helper package to process static content into dynamic content., (*1)
Examples
Below are helpful examples, however if you have not setup the shortdb package before please read the Installation guide first., (*2)
This repo contains example shortcodes and useful code showing you how to use the package in your projects:, (*3)
Installation
This package requires PHP 5.6+ (has not been tested on lower versions)., (*4)
The package works on Windows and Linux webservers (not been tested on Mac), (*5)
To install through composer you can either use composer require ferrisbane/shortdb (while inside your project folder) or include the package in your composer.json., (*6)
"ferrisbane/shortdb": "0.1.*"
Then run either composer install or composer update to download the package., (*7)
To use the package with Laravel 5 add the ShortDB service provider to the list of service providers in config/app.php., (*8)
'providers' => [
...
Ferrisbane\ShortDB\Laravel5ServiceProvider::class
...
];
Then use php artisan vendor:publish to publish the config., (*9)
If you have changed the namespace of your project you can define it inside config/shortdb.php, (*10)
'namespace' => 'App',, (*11)
Setup
Once the shortdb package has been installed on your project you will need to setup/create a shortdb class., (*12)
This shortdb class will allow the shortdb package to convert static text and process it however you want., (*13)
In laravel create a Shortcodes folder inside your app folder., (*14)
You should now have a project structure that looks like: /app/Shortcodes/, (*15)
Inside the Shortcodes folder create a php file, name it on what this class will process., (*16)
For example a file named: FontAwesome.php. This Font Awesome file will allow us process font awesome icons., (*17)
You can create as many shortcode files as needed in your project., (*18)
Take a look at our example FontAwesome Shortcode: Example Shortcode (FontAwesome), (*19)
Inside the shortcode class there are variables and functions that are used to load and process the shortcode:, (*20)
-
The $code variable is used to define the unique name/code of this shortcode., (*21)
-
The $description variable is currently unused but will be used to describe what this shortcode does., (*22)
-
The $arguments variable is an array of arguments the shortcode will accept, e.g. 'icon'.
Inside the 'icon' argument you can define if it is required:, (*23)
'icon' => [
'required' => true
],
- The process function will
process the shortcode. public function process(array $arguments)
The shortdb package will pass all arguments to this function, you can now process what you require inside, once done return your processed string., (*24)
Currently the getJavascriptDescriptor and getOptions functions are unused., (*25)
Usage
Using the shortdb package is easy., (*26)
First you will need a string, this can be from a database, env, config etc., (*27)
Lets say the string we have is:, (*28)
$string = '{fa|icon:camera-retro}';
The shortdb package will look for shortcodes within curly brackets {} inside the passed string., (*29)
The shortcode can be anywhere within the string and you can have multiple different shortcodes, for example:, (*30)
$string = 'content... {fa|icon:camera-retro} ...more content... {fa|icon:cog} ...even more content';
The shortcode allows multiple arguments, the first in the above example: fa tells the shortdb package what shortcode to use., (*31)
This is defined in the shortcode php file using the $code variable. This will need to be unique., (*32)
We can then add more arguments to the shortcode, these are split using a pipe | for example shortcodekey|argument1|argument2., (*33)
Each argument can be passed values (just like a key value pair). To pass values with the argument use a colon : for example icon:cog, (*34)
This will pass an argument to your shortcode process function. You can get the value using, (*35)
$arguments['icon']
If we passed icon:cog in the shortcode, when calling the above inside the process function we will retrieve cog., (*36)
Processing a string
Passing the 'unprocessed' string to the below function/helper will then process into a dynamic content,
in our example it will be a FontAwesome html icon tag., (*37)
For example {fa|icon:cog|spin:true} will be processed into <i class="fa fa-cog fa-spin" aria-hidden="true"></i>, (*38)
Processing a FontAwesome icon is just the start, by creating your own you can process whatever you need., (*39)
For example {ip|country:name} can be processed into United Kingdom based on the connecting client ip address., (*40)
Or {price|product:my-product-slug|currency:gbp} into £100 or {price|product:another-product|currency:usd} into $259, (*41)
This is useful if you want to place dynamic content (product price) within 'static' content (e.g. database content).
Useful if using a text editor/wysiwyg where html or dynamic would not work., (*42)
Function/Helper
In laravel we can pass our string to the shortdb service container instance:, (*43)
app('shortdb')->process($string);
Or as the package comes with a useful laravel helper function, just call the helper and pass it a string, you will then get your processed string back, (*44)
shortdb($string);
Using the helper in blade:, (*45)
{!! shortdb($string) !!}
Wallogit.com
