Ajouter un package Laravel dans un plugin OctoberCMS
Voici un petit tutoriel rapide qui explique comment ajouter un package Laravel dans un plugin OctoberCMS
Depuis que nous nous lançons sur OctoberCMS, nous développons quelques plugins sur ce dernier et nous avons souhaitons avoir la possibilité de générer un PDF depuis du HTML.
En fouillant un peu sur le net, nous sommes tombé sur ce package: https://github.com/barryvdh/laravel-dompdf
Nous l’avions déjà utilisé auparavant et nous en étions ravi.
Or, quand on fait du Laravel c’est assez simple, on lance une commande avec composer, puis on ajoute le provider et l’alias et zou, ça roule parfaitement.
Sur October CMS c’est un peu différent. Lorsqu’on installe un plugin depuis l’interface, on ne peux pas demander à l’utilisateur de lancer son terminal, rentrer 2 commandes et modifier des fichiers si il le faut.
Cela dit, et encore une fois, tout est bien pensé sur OctoberCMS.
La manipulation est assez simple, et voici la démarche:
1 – Créer son fichier composer.json dans le dossier du plugin.
Il faut créer votre fichier composer.json dans le dossier du plugin, mettre les dépendances que l’on souhaite dedans et, très important, bien penser à rajouter ces lignes suivantes:
"scripts": {
"post-create-project-cmd": [
"php artisan key:generate",
"php artisan package:discover"
],
"post-update-cmd": [
"php artisan october:util set build",
"php artisan package:discover"
]
}Voici le rendu final de notre composer.json de notre plugin d’erp (control ERP)
Nous avons rajouté uniquement le paquet: barryvdh/laravel-dompdf
{
"name": "prestasafe/erp",
"description": "Erp Plugin for OctoberCMS",
"type": "october-plugin",
"require": {
"barryvdh/laravel-dompdf": "^0.8.4"
},
"scripts": {
"post-create-project-cmd": [
"php artisan key:generate",
"php artisan package:discover"
],
"post-update-cmd": [
"php artisan october:util set build",
"php artisan package:discover"
]
},
"license": "MIT",
"authors": [
{
"name": "Guillaume Batier",
"email": "contact@prestasafe.com"
}
]
}2 – Rendez vous dans votre dossier racine d’October CMS avec votre terminal puis lancer la commander:
composer updateAttention de ne pas lancer cette commande dans le dossier du plugin !
Puis dans votre plugin, au niveau du fichier Plugin.php,
rajouter cette méthode:
public function bootPackages()
{
// Get the namespace of the current plugin to use in accessing the Config of the plugin
$pluginNamespace = str_replace('\\', '.', strtolower(__NAMESPACE__));
// Instantiate the AliasLoader for any aliases that will be loaded
$aliasLoader = AliasLoader::getInstance();
// Get the packages to boot
$packages = Config::get($pluginNamespace . '::packages');
// Boot each package
foreach ($packages as $name => $options) {
// Setup the configuration for the package, pulling from this plugin's config
if (!empty($options['config']) && !empty($options['config_namespace'])) {
Config::set($options['config_namespace'], $options['config']);
}
// Register any Service Providers for the package
if (!empty($options['providers'])) {
foreach ($options['providers'] as $provider) {
App::register($provider);
}
}
// Register any Aliases for the package
if (!empty($options['aliases'])) {
foreach ($options['aliases'] as $alias => $path) {
$aliasLoader->alias($alias, $path);
}
}
}
}4 – Enfin, toujours dans votre dossier du plugin, dans le fichier config/config.php
chargez le provider et les alias.
[
'barryvdh/laravel-dompdf' => [
// Service providers to be registered by your plugin
'providers' => [
'Barryvdh\DomPDF\ServiceProvider',
],
// Aliases to be registered by your plugin in the form of $alias => $pathToFacade
'aliases' => [
'PDF' => 'Barryvdh\DomPDF\Facade',
],
// The namespace to set the configuration under. For this example, this package accesses it's config via config('purifier.' . $key), so the namespace 'purifier' is what we put here
'config_namespace' => 'dompdf',
'config' => [
'show_warnings' => false, // Throw an Exception on warnings from dompdf
'orientation' => 'portrait',
'defines' => array(
/**
* The location of the DOMPDF font directory
*
* The location of the directory where DOMPDF will store fonts and font metrics
* Note: This directory must exist and be writable by the webserver process.
* *Please note the trailing slash.*
*
* Notes regarding fonts:
* Additional .afm font metrics can be added by executing load_font.php from command line.
*
* Only the original "Base 14 fonts" are present on all pdf viewers. Additional fonts must
* be embedded in the pdf file or the PDF may not display correctly. This can significantly
* increase file size unless font subsetting is enabled. Before embedding a font please
* review your rights under the font license.
*
* Any font specification in the source HTML is translated to the closest font available
* in the font directory.
*
* The pdf standard "Base 14 fonts" are:
* Courier, Courier-Bold, Courier-BoldOblique, Courier-Oblique,
* Helvetica, Helvetica-Bold, Helvetica-BoldOblique, Helvetica-Oblique,
* Times-Roman, Times-Bold, Times-BoldItalic, Times-Italic,
* Symbol, ZapfDingbats.
*/
"font_dir" => storage_path('fonts/'), // advised by dompdf (https://github.com/dompdf/dompdf/pull/782)
/**
* The location of the DOMPDF font cache directory
*
* This directory contains the cached font metrics for the fonts used by DOMPDF.
* This directory can be the same as DOMPDF_FONT_DIR
*
* Note: This directory must exist and be writable by the webserver process.
*/
"font_cache" => storage_path('fonts/'),
/**
* The location of a temporary directory.
*
* The directory specified must be writeable by the webserver process.
* The temporary directory is required to download remote images and when
* using the PFDLib back end.
*/
"temp_dir" => sys_get_temp_dir(),
/**
* ==== IMPORTANT ====
*
* dompdf's "chroot": Prevents dompdf from accessing system files or other
* files on the webserver. All local files opened by dompdf must be in a
* subdirectory of this directory. DO NOT set it to '/' since this could
* allow an attacker to use dompdf to read any files on the server. This
* should be an absolute path.
* This is only checked on command line call by dompdf.php, but not by
* direct class use like:
* $dompdf = new DOMPDF(); $dompdf->load_html($htmldata); $dompdf->render(); $pdfdata = $dompdf->output();
*/
"chroot" => realpath(base_path()),
/**
* Whether to enable font subsetting or not.
*/
"enable_font_subsetting" => false,
/**
* The PDF rendering backend to use
*
* Valid settings are 'PDFLib', 'CPDF' (the bundled R&OS PDF class), 'GD' and
* 'auto'. 'auto' will look for PDFLib and use it if found, or if not it will
* fall back on CPDF. 'GD' renders PDFs to graphic files. {@link
* Canvas_Factory} ultimately determines which rendering class to instantiate
* based on this setting.
*
* Both PDFLib & CPDF rendering backends provide sufficient rendering
* capabilities for dompdf, however additional features (e.g. object,
* image and font support, etc.) differ between backends. Please see
* {@link PDFLib_Adapter} for more information on the PDFLib backend
* and {@link CPDF_Adapter} and lib/class.pdf.php for more information
* on CPDF. Also see the documentation for each backend at the links
* below.
*
* The GD rendering backend is a little different than PDFLib and
* CPDF. Several features of CPDF and PDFLib are not supported or do
* not make any sense when creating image files. For example,
* multiple pages are not supported, nor are PDF 'objects'. Have a
* look at {@link GD_Adapter} for more information. GD support is
* experimental, so use it at your own risk.
*
* @link http://www.pdflib.com
* @link http://www.ros.co.nz/pdf
* @link http://www.php.net/image
*/
"pdf_backend" => "CPDF",
/**
* PDFlib license key
*
* If you are using a licensed, commercial version of PDFlib, specify
* your license key here. If you are using PDFlib-Lite or are evaluating
* the commercial version of PDFlib, comment out this setting.
*
* @link http://www.pdflib.com
*
* If pdflib present in web server and auto or selected explicitely above,
* a real license code must exist!
*/
//"DOMPDF_PDFLIB_LICENSE" => "your license key here",
/**
* html target media view which should be rendered into pdf.
* List of types and parsing rules for future extensions:
* http://www.w3.org/TR/REC-html40/types.html
* screen, tty, tv, projection, handheld, print, braille, aural, all
* Note: aural is deprecated in CSS 2.1 because it is replaced by speech in CSS 3.
* Note, even though the generated pdf file is intended for print output,
* the desired content might be different (e.g. screen or projection view of html file).
* Therefore allow specification of content here.
*/
"default_media_type" => "screen",
/**
* The default paper size.
*
* North America standard is "letter"; other countries generally "a4"
*
* @see CPDF_Adapter::PAPER_SIZES for valid sizes ('letter', 'legal', 'A4', etc.)
*/
"default_paper_size" => "a4",
/**
* The default font family
*
* Used if no suitable fonts can be found. This must exist in the font folder.
* @var string
*/
"default_font" => "serif",
/**
* Image DPI setting
*
* This setting determines the default DPI setting for images and fonts. The
* DPI may be overridden for inline images by explictly setting the
* image's width & height style attributes (i.e. if the image's native
* width is 600 pixels and you specify the image's width as 72 points,
* the image will have a DPI of 600 in the rendered PDF. The DPI of
* background images can not be overridden and is controlled entirely
* via this parameter.
*
* For the purposes of DOMPDF, pixels per inch (PPI) = dots per inch (DPI).
* If a size in html is given as px (or without unit as image size),
* this tells the corresponding size in pt.
* This adjusts the relative sizes to be similar to the rendering of the
* html page in a reference browser.
*
* In pdf, always 1 pt = 1/72 inch
*
* Rendering resolution of various browsers in px per inch:
* Windows Firefox and Internet Explorer:
* SystemControl->Display properties->FontResolution: Default:96, largefonts:120, custom:?
* Linux Firefox:
* about:config *resolution: Default:96
* (xorg screen dimension in mm and Desktop font dpi settings are ignored)
*
* Take care about extra font/image zoom factor of browser.
*
* In images, ![]()
size in pixel attribute, img css style, are overriding
* the real image dimension in px for rendering.
*
* @var int
*/
"dpi" => 96,
/**
* Enable inline PHP
*
* If this setting is set to true then DOMPDF will automatically evaluate
* inline PHP contained within tags.
*
* Enabling this for documents you do not trust (e.g. arbitrary remote html
* pages) is a security risk. Set this option to false if you wish to process
* untrusted documents.
*
* @var bool
*/
"enable_php" => false,
/**
* Enable inline Javascript
*
* If this setting is set to true then DOMPDF will automatically insert
* JavaScript code contained within tags.
*
* @var bool
*/
"enable_javascript" => true,
/**
* Enable remote file access
*
* If this setting is set to true, DOMPDF will access remote sites for
* images and CSS files as required.
* This is required for part of test case www/test/image_variants.html through www/examples.php
*
* Attention!
* This can be a security risk, in particular in combination with DOMPDF_ENABLE_PHP and
* allowing remote access to dompdf.php or on allowing remote html code to be passed to
* $dompdf = new DOMPDF(, $dompdf->load_html(...,
* This allows anonymous users to download legally doubtful internet content which on
* tracing back appears to being downloaded by your server, or allows malicious php code
* in remote html pages to be executed by your server with your account privileges.
*
* @var bool
*/
"enable_remote" => true,
/**
* A ratio applied to the fonts height to be more like browsers' line height
*/
"font_height_ratio" => 1.1,
/**
* Use the more-than-experimental HTML5 Lib parser
*/
"enable_html5_parser" => false,
),
]
],
],
];
le tableau ‘config’ vous permet de gérer la configuration du package depuis le plugin.
Voila, vous pouvez ensuite utilisé votre package normalement.
Une fois que votre plugin sera placé sur la marketplace, le dossier vendor/ sera généré automatiquement et l’utilisateur pourra l’ajouter depuis le backoffice directement. Ou depuis composer en précisant bien le type:
"type": "october-plugin"dans le composer.json composer placera alors le plugin dans le bon dossier et fera un update pour rajouter les packages manquants.
N’hésitez pas si à commenter cela si vous avez des questions.
Enjoy 😉
