Merge pull request #1 from kethinov/1.0.0

1.0.0

.github/workflows/.ci.yml

@@ -0,0 +1,21 @@
+on: push
+name: CI
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        node-version: [10.x, 12.x, 14.x]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v1
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run coverage
+      - run: npm run codecov
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -0,0 +1,174 @@
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### Node ###
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+
+# rollup.js default build output
+dist/
+
+# Uncomment the public line if your project uses Gatsby
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# https://create-react-app.dev/docs/using-the-public-folder/#docsNav
+# public
+
+# Storybook build outputs
+.out
+.storybook-out
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Temporary folders
+tmp/
+temp/
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## Next version
+
+- Put your changes here...
+
+## 1.0.0
+
+- Initial version.

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# How to contribute
+
+## Before opening a pull request
+
+- Be sure all tests pass: `npm t`.
+- Ensure 100% code coverage and write new tests if necessary: `npm run coverage`.
+- Add your changes to `CHANGELOG.md`.
+
+## Release process
+
+If you are a maintainer of this module, please follow the following release procedure:
+
+- Merge all desired pull requests into master.
+- Bump `package.json` to a new version and run `npm i` to generate a new `package-lock.json`.
+- Alter CHANGELOG "Next version" section and stamp it with the new version.
+- Paste contents of CHANGELOG into new version commit.
+- Open and merge a pull request with those changes.
+- Tag the merge commit as the a new release version number.
+- Publish commit to npm.

LICENSE.md

@@ -0,0 +1,5 @@
+License
+===
+
+All original code in this project is licensed under the [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). Commercial and noncommercial use is permitted with attribution.
+

README.md

@@ -1,2 +1,67 @@
 # express-php-view-engine
-🐘 Allows you to use PHP as a view engine for Express applications.
+
+[![Build Status](https://github.com/rooseveltframework/express-php-view-engine/workflows/CI/badge.svg
+)](https://github.com/rooseveltframework/express-php-view-engine/actions?query=workflow%3ACI) [![codecov](https://codecov.io/gh/rooseveltframework/express-php-view-engine/branch/master/graph/badge.svg)](https://codecov.io/gh/rooseveltframework/express-php-view-engine) [![npm](https://img.shields.io/npm/v/express-php-view-engine.svg)](https://www.npmjs.com/package/express-php-view-engine)
+
+This module allows you to use [PHP](https://php.net) as a templating system for [Express framework](https://expressjs.com) applications. This module was built and is maintained by the [Roosevelt web framework](https://github.com/rooseveltframework/roosevelt) [team](https://github.com/orgs/rooseveltframework/people), but it can be used independently of Roosevelt as well.
+
+## Usage
+
+First declare `express-php-view-engine` as a dependency in your app.
+
+Then set PHP as a view engine in your Express app:
+
+```js
+const express = require('express')
+const app = express()
+const php = require('express-php-view-engine')
+
+// setup php templating engine
+app.set('views', path.join(__dirname, 'templates'))
+app.set('view engine', 'php')
+app.engine('php', php.__express)
+
+// define a route
+app.get('/', (req, res) => {
+  res.render('index.php', {
+    hello: 'world'
+  })
+})
+```
+
+Then, assuming your `templates/index.php` looks like this:
+
+```php
+<p><?=$hello?></p>
+```
+
+The ouptut will be:
+
+```html
+<p>world</p>
+```
+
+Note: This module presumes that the system you run this on has PHP installed and that it's in your PATH.
+
+## Configuration
+
+As shown in the above example, `express-php-view-engine` will register values from the Express model as global variables in your PHP script by default. You can disable this behavior if desired two ways:
+
+Disable registering globally:
+
+```js
+const php = require('express-php-view-engine')
+php.disableRegisterGlobalModel()
+// can be reenabled by calling php.enableRegisterGlobalModel()
+```
+
+Disable registering on a per route basis:
+
+```js
+app.get('/', (req, res) => {
+  res.render('index.php', {
+    _REGISTER_GLOBAL_MODEL: false,
+    hello: 'world'
+  })
+})
+```

index.js

@@ -0,0 +1,35 @@
+const execa = require('execa')
+const circular = require('circular')
+const path = require('path')
+const settings = {}
+settings.disableRegisterGlobalModel = false
+
+async function render (template, model, callback) {
+  model._TEMPLATE = template
+  if (typeof model._REGISTER_GLOBAL_MODEL === 'undefined') { // if not overridden by the model
+    // then source the setting from the global settings
+    if (settings.disableRegisterGlobalModel) {
+      model._REGISTER_GLOBAL_MODEL = false
+    } else {
+      model._REGISTER_GLOBAL_MODEL = true
+    }
+  }
+  model._REGISTER_GLOBAL_MODEL = !!model._REGISTER_GLOBAL_MODEL // force a boolean
+  model._VIEWS_PATH = model.settings.views // pass views path to php
+  const jsonModel = JSON.stringify(model, circular()) // stringify with circular references stripped
+  const { stdout } = await execa('php', [path.join(__dirname, '/loader.php')], { input: jsonModel }) // e.g. php loader.php <<< '["array entry", "another", "etc"]'
+  const renderedTemplate = stdout
+  callback(null, renderedTemplate)
+}
+
+function disableRegisterGlobalModel () {
+  settings.disableRegisterGlobalModel = true
+}
+
+function enableRegisterGlobalModel () {
+  settings.disableRegisterGlobalModel = false
+}
+
+module.exports.__express = render
+module.exports.disableRegisterGlobalModel = disableRegisterGlobalModel
+module.exports.enableRegisterGlobalModel = enableRegisterGlobalModel

loader.php

@@ -0,0 +1,17 @@
+<?
+// get model data from STDIN and decode the JSON into a proper PHP object
+$model = json_decode(stream_get_contents(STDIN));
+
+// declare global variables for each model variable (if the setting to do so is enabled)
+if ($model->_REGISTER_GLOBAL_MODEL) {
+  foreach ($model as $key => $value) {
+    $$key = $value;
+  }
+}
+
+// add express templates path to php includes path
+set_include_path($model->_VIEWS_PATH);
+
+// render the template
+include "$model->_TEMPLATE";
+?>