owenmelbz / illumipress
Simple wrapper for the illuminate support, http response, request, validation, zttp, cache, encryption, blade templating and whoops error handler for WordPress
Requires
- filp/whoops: ^2.1
- illuminate/cache: 5.*
- illuminate/encryption: 5.*
- illuminate/http: 5.*
- illuminate/validation: 5.*
- illuminate/view: 5.*
- kitetail/zttp: ^0.3.0
Requires (Dev)
- phpunit/phpunit: ^7.0
README
IllumiPress
IllumiPress is a simple wrapper for some of the laravel 5 illuminate packages, it allows users to integrate some of the joyful features of Laravel into wordpress.
We currently integrate WordPress with Laravel Blade, HTTP Requests, Responses, Validator and Support (e.g collections, dd, string helpers etc), ZTTP, Caching (redis, memcached, file) and Ecryption
Installation
The easiest way to install is via composer e.g composer require owenmelbz/illumipress
from within your project root.
Even if your project is not using composer you can use the above command, but then you must manually include vendor/autoload.php
in your project, for WordPress consider using the functions.php
Features
As the illuminate packages require the illuminate/support package, you also get access to an array of magic such as
- collections via
collect
- both
dump
anddd
- array helpers such as
data_get
,array_wrap
,array_dot
etc - string helpers e.g
ends_with
,starts_with
,str_contains
,str_random
- logical helpers such as
optional
,tap
,throw_if
- access to Guzzle via
kitetail\zttp
and ahttp()
helper - laravel blade template rendering using
filename.blade.php
allowingview('component.sidebar')
etc
You can see a full list of included components https://github.com/illuminate/support
Usage
The package has a child class which extends the core illuminate classes to add some additional helper functions.
Request Class
This does not currently have any custom functionality, you should be able to use the documentation provided https://laravel.com/docs/5.6/requests - you have access to a global helper request()
to get a new instance of the request object, so you can do things such as request()->get('my_posted_data', 'default value')
etc.
Response Class
The main difference between the Laravel and this implementation is that typically you must manually use Symfony's "send()" method to complete the request e.g.
return response(['hello' => 'world'])->send();
There are however custom helpers on top to provide a consistent ajax style responses, ajax(), success(), error()
// alias of ->success()
// Sends a JSON response formatted into a JSONSchema'esque structure
return response([
'hello' => 'world'
])->ajax();
// Returns 200 header
{
"data": {"hello": "world"},
"meta": {"success": true}
}
// You can also send a JSON response with error headers
return response('Sorry something went wrong')->error(422);
// Returns a 422 error
{
"data": "Sorry something went wrong",
"meta": {"success": false}
}
You can also add custom meta to the response, useful for things such as "next" and "prev" data.
return response('My response')->addMeta(['key' => 'value'])->send();
You can completely overwrite the meta using setMeta
method.
Validation class
This provides 2 extra methods on top of the validation class, firstly the ability to return a formatted list of errors using $validator->formattedErrors()
and an ajax result using the previously mentioned automatic formatting by $validator->response()
.
You have the full validation class (https://laravel.com/docs/5.6/validation) under there to use such as
$validator = validator(request()->all(), [
'name' => 'required',
'email' => 'required|email'
]);
if ($validator->fails()) {
return $validator->response();
}
// Outputs
{
"data": [
{
"param": "name",
"messages": [
"the name field is required",
]
}
],
"meta": {
"success": false
}
}
By default we only include the default Laravel i18n error messages, you can follow the Laravel documentation for passing in custom messages https://laravel.com/docs/5.6/validation#custom-error-messages
If you need to use translations you can load your custom messages file e.g
$validator = validator($data, $rules);
$validator->setLanguageFile(__DIR__ . '/i18n/french.php');
Laravel Blade
Blade has also been included to allow a more fluent syntax for rendering templates.
By default it is disabled - however you can turn it on by using turn_blade_on()
and to turn off using turn_blade_off()
If you name your files template.blade.php
Blade can render the template directly, however, if you enable blade and have normal template.php
files, it will create a dynamic copy within the wp-content/uploads/.cache/
which will update each time you make a file change.
The integration is loosely based off https://github.com/tormjens/wp-blade which means you get some starter directives such as:
@post
<h1>{{ the_title() }}</h1>
<p>@field('page_intro')</p>
@has('extra_intro')
<p>@field('extra_intro')</p>
@endhas
<ul>
@repeater('services')
<li>@subfield('service_name')</li>
@endrepeater
</ul>
<div class="related">
@wpquery(['author_id' => 21])
{{ the_title() }}
@endwpquery
</div>
@endpost
You can return a rendered view by using the view('components.sidebar')
helper
Cache
The illuminate\cache
package is also included which is available by a global cache()
helper, so you can do things such as cache()->put('user_10', 'Taylor')
etc.
Currently you can use the file, memcached and redis driver for caching with some basic configurations, Config items are exposed by the following CONSTANTS.
- Redis
--
REDIS_CONNECTION
(default =default
) --REDIS_PREFIX
(default =illumipress
) --REDIS_HOST
(default =127.0.0.1
) --REDIS_PORT
(default =6379
) - File
--
ILLUMINATE_CACHE
(default =wp-uploads/.cache
) - Memcached
--
MEMCACHED_PREFIX
(default =illumipress
) --MEMCACHED_HOST
(default =127.0.0.1
) --MEMCACHED_PORT
(default =11211
)
An example usage may be
define('ILLUMINATE_CACHE', './cache');
$tweets = cache()->remember('recent_tweets', $cacheLifeTimeInMinutes = 20, function () {
return $tweets = http('https://twitter.com/illumipress.json');
));
Encryption
The illuminate/encrypter
is also included for handling certain sensitive data which can be used via the the encryption
global helper.
By default it will look for a constant called ILLUMINATE_ENCRYPTION_KEY
which should be a 16 character key which will be used to encrypt the data. Of course you might want to make this unique to each user, to prevent other users decrypting others data.
You can pass in your own encryption key into the helper e.g
$enc = encryption($user->private_key);
$encryptedData = $enc->encrypt('My secret');
$decryptedData = $enc->decrypt($encryptedData);
echo $decryptedData; // My Secret
Whoops
By default (sorry) we turn on the filp/whoops
error handler to enable more friendly errors.
You can turn this off and on via turn_whoops_off()
and turn_whoops_on()
However when your WordPress configuration defines WP_DEBUG_DISPLAY
as false
Whoops will disable itself - regardless of what you type.
HTTP Client / Guzzle / cURL / zttp
We also include the kitetail/zttp
library for a simple curl access via the http()
helper, for full information we recommend checking out the zttp GitHub documentation
$stringResponse = http('https:/www.google.com');
for a simple curl GET request you can use the above, for more complicated requests you can use the fuller syntax, which returns an instance of ZttpResponse
$response = http()->post('https://www.google.com/', ['q' => 'my query']);
if ($response->isOkay()) {
echo $response->body();
echo $response->json();
echo etc...
}
As zttp
uses Guzzle under the hood, which means you can also get access to the full guzzle suite and do things such as (new Guzzle\Client)->setBaseUri('https://www.google.com/')->post('search', ['q' => 'query''])
;
License
This is a completely free and open source project, feel free to use it for anything you like, if you wish to modify and redistribute it, however, please give some credit back to the original repository.