README.md

LC-quick-shortcodes

WordPress shortcodes don't need any presentation: they simply are the most used and effective way to turn short texts into complex structures. Using this tiny PHP class you'll be able to use the same engine also on your project!

As little extra, the class already executes few common BBcodes (continue reading to know which ones)

• It is just 5KB big and doesn't have any dependency.
  
• Supports any server running PHP 5.4 and later.
  
• Shortcodes can be nested and you can use HTML within.

How to use

Include the class in the project and initialize it with its namespace:

include_once('lc_quick_shortcodes.php');
$lcqs = new lcweb\quick_sc\lc_quick_shortcodes;

Shortcodes registration

Here are two examples: the first says Hello!, while the second prints a code block.

/**
 * Register a new shortcode  
 * 
 * @param (string) 			$name = shortcode's name
 * @param (array) 			$defaults = shortcode parameters and their defaults
 * @param (bool) 			$has_contents = whether shortcode will have contents or not
 * @param (func|string) 	$callback = callback function name or anonymous function
 */

$lcqs->register('hello', array(), false, function($atts, $contents) {	
	return '<h1>Hello!</h1>';
});

$lcqs->register('title', array('lang'=>'html'), true, function($atts, $contents) {	
	return '<pre class="language-'. $atts['lang'] .'"><code>'. $contents .'</code></pre>';
});

Analyzing function parameters:

1. sets shortcode's name. Must not have spaces in it.
   
   
2. defines shortcode parameters and their defaults. In this example we expect a parameter called lang and it has a default value of html.
   
   Then using [code][/code] the resulting code will still use html, while using [code lang="php"][/code] you will override the default value.
   
   
3. FALSE if there are no contents (first example), TRUE if contents will be used within (second example)
   
   
4. May be a function name triggering a callback or an anonymous function (as used in the example).
   The function will have two parameters: and contents.
   
   
   1. shortcode attributes - an associative array containing every attribute found in the shortcode implementation. It contains also custom ones not declared in shortcode registration (eg. [hello param1="hey!"] )
   2. contents - this is empty if $has_contents is set to false

Shortcodes execution

Once everything is properly registered, just let the class execute your string

/**
 * Execute shortcodes in a text string
 *
 * @param (string) $txt = text
 * @param (bool) $bbcodes = whether to execute found BBcodes first (see https://www.bbcode.org/reference.php )
 *
 * @return (string) executed text
 */

$string = 'Lorem ipsum [code lang="php"]dolor sit amet[/code]';
echo $lcqs->process($string, $bbcodes = true);

/* Resulting string:
 * Lorem ipsum <pre class="language-php"><code>dolor sit amet</code></pre>
 */

First parameter is your string, while second ones sets whether to execute also BBcodes or not.

Here's the list of supported BBcodes:

Example	Description
[b] test [/b]	bold text
[i] test [/i]	italic text
[u] test [/u]	underlined text
[code] test [/code]	PRE code block
[size=20] test [/size]	sets font size (in pixels)
[color=#ff0000] test [/color]	sets text color (hex vlue)
[url] http://mypage.com [/url]	creates a link
[img] http://mypage.com/myimage.jpg [/img]	creates an image
[ul] [*] test 1 [*] test 2 [/ul]	unordered list
[ol] [*] test 1 [*] test 2 [/ol]	ordered list

Summarizing

include_once('lc_quick_shortcodes.php');
$lcqs = new lcweb\quick_sc\lc_quick_shortcodes;

$lcqs->register('title', array('lang'=>'html'), true, function($atts, $contents) {	
	return '<pre class="language-'. $atts['lang'] .'"><code>'. $contents .'</code></pre>';
});


$string = 'Lorem ipsum [code lang="php"]dolor sit amet[/code]';
echo $lcqs->process($string, $bbcodes = true);

Isn't it quick?

---

Copyright © Luca Montanari (aka LCweb)