Recommend this page to a friend! |
Download |
Info | Documentation | Screenshots | Files | Install with Composer | Download | Reputation | Support forum | Blog | Links |
Ratings | Unique User Downloads | Download Rankings | ||||
Not yet rated by the users | Total: 313 | All time: 7,284 This week: 39 |
Version | License | PHP version | Categories | |||
pwassist 0.10 | MIT/X Consortium ... | 5.2 | PHP 5, Web services, Code Generation |
Description | Author | |||
This package can generate service workers Progressive Web App files. Innovation Award
|
Small PHP class for automated PWA (Progressive Web Applications) files creation : service-worker (javascript), manifest.json, and generating icon set for all needed resoultions from a single image.
Simplest way to start using PWAssist, is following: - in the root folder of your project create simple "make" php file like this (for example, pwamake.php):
// file : pwamake.php
include_once('../src/PWAssist.php');
PWAssist::init();
Note that __SW Template File__ is a select box, because we have registered templates in the global config file (described later).
After performing "Save parameters" you will have "pwa_config.xml" with all desired configuration. Now you can press any of "action" button (icons, Service worker file, manifest.json)
or run pwamake.php from the shell:
$ php pwamake.php {command} [{command} ...]
where {command} is one of icons, manifest, sw, all.
XML configuration file for your application has a name "pwa_config.xml" and placed in the "current" folder with your pwamake.php.
You can edit this file manuallty in text editor or enter all needed values in HTML form and press "Save parameters" button. Here is a supported parameters list. - __App id__ (in XML - appId) - Uniquie ID for your application. Must comply "variables naming" rules. Used to form cache name in case you leave it empty. - __App Name__ (appName) - Application name ( value for __name__ in manifest.json) - __App Short Name__ (appShortName) - short application name (value for __short_name__ in manifest.json) - __App Description__ (appDesc) - application description (value for __description__ in manifest.json) - __Start URI__ (appDesc) - application description (value used as __start_url__ in manifest.json and as a first item in precache file list inside SW script) - __Home Folder__ : by default work performed on current folder, you started your pwamake.php from. If you need to have another "document root" for your files, change default "./" to a right path (relative to current folder). - __App Version__ (appVersion) - application current version (will be used in cacheName in service worker, so after changing version newly generated SW script could force clearing from old cache and populate new one) - __Lang__ (lang) will be used in manifest "lang" parameter. - __SW template file__ (swTemplate) : here you can set your service-worker template file , to use instead of "standard" built-in code. If you set your own name and such file won't be found in the folder with PWAssist.php, service-worker creating task will fail.
Standard template code for service worker code is inside PWAssist.php module. It is based on service worker code from Google developer examples (cache-First approach) and slightly modified to be able insert "parameterized" blocks, like generated filelist to cache, cache name, string for detecting "dynamic" URL that should be requested directly without caching.
If you open your saved pwa_config.xml in text editor, you may find some non-empty parameters missing. This occurs when their values are equal to "default" ones.
You have to prepare "mustashed" macros inside your template to be replaced with final values. - {version} will be replaced with App Version, - {cachename} - cacheName parameter - {dynamicTest} will be changed to js code for checking for all "dynamicPart" items, so any matching will activate request to Server. - {created_date} for date and time of creation SW module, - {author} will be replaced with Your author's name, - {copyright} - your copyright string (author and copyright can be set in global configuration file, see below) - {filelist} - generated precached filelist will be inserted in place of this string.
Default values for all application parameters are hard-coded inside PWAssist.php, in static variable $defaultCfg. But if you want to change them, you can create another XML file: __PWAssist-global-cfg.xml__. It must be saved in one folder with PWAssist.php module.
Any parameter included in this file will overwrite "hard-coded" default value. For example, here you can set your author's name and copyright strings that will apply to all your applications.
Another feature of global config : you can register your service-worker code templates here, so you can choose one of them for generating final SW module.
Below is an example of PWAssist-global-cfg.xml with a registering two sw templates block:
<?xml version="1.0" encoding="UTF-8"?>
<PWA-config>
<author>My name</author>
<copyRight>my little big company</copyRight>
<ignoreFolders>res</ignoreFolders>
<ignoreFiles>test.html,_temp.,.log</ignoreFiles>
<fileSizeLimit>256K</fileSizeLimit>
<cacheName>myapp_cache</cacheName>
<dynamicPart>?refresh=</dynamicPart>
<lang>en-EN</lang>
<iconResolutions>44,128,152,256</iconResolutions>
<baseIcon>res/icon.png</baseIcon>
<iconFilenameTemplate>img/iconapp-{size}.png</iconFilenameTemplate>
<backgroundColor>#CCCCFF</backgroundColor>
<themeColor>#AACCFF</themeColor>
<swTemplates>
<swTemplate src="PWAssist-cacheFirst.js" title="Cache-First" />
<swTemplate src="PWAssist-networkFirst.js" title="Network-First" />
</swTemplates>
</PWA-config>
When PWAssist has a non-empty list of SW templates, it will create "select-box" for "SW Template" field instead of standard text input, in the "Application parameters" form.
Sample global configuration file is in src folder.
__Note__ : it contains registered SW templates just to show you how to use this feature. Respective js files not included, so if you try to select one of them for generating service-worker in your application, the task will fail !
I hope you understand that source image for all icons must have resolution greater or equal to the most large icon. Otherwise you will get upscaled pictures looking not so good.
PNG format is preferred for source image, as it supports transparency. Other source image types supported (gif, webp, jpg), but if you choose some ot them, PWAssist will try to create png icons from it, probably without transparency areas.
Alhough PHP has a function for opening WEBP image files (imagecreatefromwebp()), I found it can work with artefacts (color shifting or even black color on the whole loaded picture). So be ready to get strange results if you use WEBP source file for your icons.
Working sample demonstrating "service page" with all buttons for creating PWA modules : demo/pwamake.php
Distributed under MIT License : http://opensource.org/licenses/MIT
Screenshots (1) | ||
Files (11) | / | demo |
File | Role | Description | ||
---|---|---|---|---|
res (1 file) | ||||
index.html | Data | Example of page using a service worker | ||
pwamake.php | Aux. | Auxiliary script | ||
pwa_config.xml | Data | Auxiliary data |
Files (11) | / | docs |
File | Role | Description |
---|---|---|
PWAssist-butts.png | Icon | Icon image |
PWAssist-form.png | Icon | Icon image |
Files (11) | / | src |
File | Role | Description |
---|---|---|
PWAssist-global-cfg.xml | Data | Auxiliary data |
PWAssist.php | Class | Class source |
The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page. |
Install with Composer |
Version Control | Unique User Downloads | Download Rankings | |||||||||||||||
90% |
|
|
Applications that use this package |
If you know an application of this package, send a message to the author to add a link here.