typisttech / wp-kses-view
Safely rendering for WordPress, the OOP way
Fund package maintenance!
typist.tech/donation
Installs: 37 191
Dependents: 4
Suggesters: 0
Security: 0
Stars: 6
Watchers: 3
Forks: 3
Open Issues: 1
Requires
- php: ^7.2
Requires (Dev)
Suggests
- typisttech/imposter-plugin: Wrap all composer vendor packages inside your own namespace, to prevent collisions when multiple plugins use this library
- typisttech/wp-admin-tabs: Create tabbed navigation for WordPress admin dashboard, the OOP way
- typisttech/wp-better-settings: A simplified OOP implementation of the WP Settings API
- typisttech/wp-contained-hook: Lazily instantiate objects from dependency injection container to WordPress hooks (actions and filters)
- typisttech/wp-tabbed-admin-pages: Create WordPress admin pages with tabbed navigations, the OOP way
README
Safely rendering for WordPress, the OOP way.
- Install
- Usage
- Frequently Asked Questions
- Why some HTML tags are stripped out?
- Is this a plugin?
- What to do when wp.org plugin team tell me to clean up the
vendor
folder? - Can two different plugins use this package at the same time?
- Do you have real life examples that use this package?
- It looks awesome. Where can I find some more goodies like this?
- Support
- Developing
- Running the Tests
- Feedback
- Change log
- Security
- Contributing
- Credits
- License
Install
Installation should be done via composer, details of how to install composer can be found at https://getcomposer.org/.
$ composer require typisttech/wp-kses-view
You should put all WP Kses View
classes under your own namespace to avoid class name conflicts.
Usage
Static Example
<?php // This is `template.php`. echo '<h1>Hello World!</h1>'; echo '<p>Using PHP echo</p>'; ?> <p>Or, it can be plain HTML</p> <script>alert('XSS hacking!');</script>
use TypistTech\WPKsesView\View; $template = '/path/to/template.php'; $view = new Factory::build($template); $view->render(); // This echos: // <h1>Hello World!</h1> // <p>Using PHP echo</p> // <p>Or, it can be plain HTML</p> // alert('XSS hacking!');
Note that <script>
has been sanitized.
Render with Context
Example
// This is `template.php`. printf( '%1$s has %2$d dragons.', $context->name, $context->dragons );
use TypistTech\WPKsesView\View; $template = '/path/to/template.php'; $context = (object) [ 'name' => 'Daenerys Targaryen', 'dragons' => 3, ]; $view = new Factory::build($template); $view->render($context); // This echos: // Daenerys Targaryen has 3 dragons.
View
__construct(string $template, array $allowedHtml)
View
constructor.
- @param string $template Filename of the template to render.
- @param array $allowedHtml List of allowed HTML elements.
$allowedHtml
will later be passed to wp_kses
.
wp_kses_allowed_html('post')
is a good start if you not sure which HTML tags to use.
$template = '/path/to/my/template.php'; $view = new View( $template, wp_kses_allowed_html('post') );
render($context = null)
Echo the view safely with optional context object.
- @param mixed $context Optional. Context object for which to render the view.
$view->render(); $view->render($someObject);
toHtml($context = null): string
Convert the view to safe HTML.
- @param mixed $context Optional. Context object for which to render the view.
$html = $view->toHtml(); $htmlWithContext = $view->toHtml($someObject);
If you pass in a context object, you can reference it in your template as $context
.
Think $context
as the M
in MVC pattern.
Template
A template can be anything, not limited to .php
files. Common use cases are:
.php
.html
.js
If you pass in a context object, you can reference it in your template as $context
.
Think templates are .erb
files under app/view
directory in a Rails app.
Helpers
This package provides Factory
, ViewAwareTrait
and NullView
to reduce boilerplate code for common use cases.
Check their well-documented source code and their tests to learn more.
Frequently Asked Questions
Why some HTML tags are stripped out?
This is the heart of this package, removing dangerous HTML tags during rendering.
To allow a HTML tag:
- Add the tag when instantiating a
view
object.
Check wp_kses
's document to learn more.
When in doubt, wp_kses_allowed_html('post')
is a good start.
Is this a plugin?
No, this is a package that should be part of your plugin.
What to do when wp.org plugin team tell me to clean up the vendor
folder?
Re-install packages via the following command. This package exports only necessary files to dist
.
$ composer install --no-dev --prefer-dist --optimize-autoloader
Can two different plugins use this package at the same time?
Yes, if put all WP Kses View
classes under your own namespace to avoid class name conflicts.
Do you have real life examples that use this package?
Here you go:
Add your own plugin here
It looks awesome. Where can I find some more goodies like this?
- Articles on Typist Tech's blog
- Tang Rufus' WordPress plugins on wp.org
- More projects on Typist Tech's GitHub profile
- Stay tuned on Typist Tech's newsletter
- Follow Tang Rufus' Twitter account
- Hire Tang Rufus to build your next awesome site
Support
Love wp-kses-view
? Help me maintain it, a donation here can help with it.
Why don't you hire me?
Ready to take freelance WordPress jobs. Contact me via the contact form here or, via email info@typist.tech
Want to help in other way? Want to be a sponsor?
Contact: Tang Rufus
Developing
To setup a developer workable version you should run these commands:
$ composer create-project --keep-vcs --no-install typisttech/wp-kses-view:dev-master
$ cd wp-kses-view
$ composer install
Running the Tests
TODO: Re-add tests.
See: https://github.com/TypistTech/wp-kses-view/commit/45f95d3f1f062c51ddbd8a5da7d6e8317fccff97
Feedback
Please provide feedback! We want to make this package useful in as many projects as possible. Please submit an issue and point out what you do and don't like, or fork the project and make suggestions. No issue is too small.
Change log
Please see CHANGELOG for more information on what has changed recently.
Security
If you discover any security related issues, please email wp-kses-view@typist.tech instead of using the issue tracker.
Contributing
Please see CONTRIBUTING and CODE_OF_CONDUCT for details.
Credits
WP Kses View is a Typist Tech project and maintained by Tang Rufus, freelance developer for hire.
Full list of contributors can be found here.
License
WP Kses View is licensed under the GPLv2 (or later) from the Free Software Foundation. Please see License File for more information.