Skip to content

npm-php
npm-php

Home

Last edited by Vadym Gidulian
Page history

npm-php

Description

Project will be deployed to server and processed with npm and gulp.

npm is also used for dependency management and local testing. Docker and Docker Compose are used to provide PHP interpreter.

Project structure

Default project structure is the following:

.
├── dist
|   ├── css
|   |   └── style.all.min.css
|   ├── img
|   ├── js
|   |   └── script.all.min.js
|   ├── index.html / index.php
|   ├── *.html
|   ├── *.php
|   ├── *
|   |   └── *.html
|   └── *
|       └── *.php
├── src
|   ├── css
|   |   └── *.css
|   ├── img
|   ├── js
|   |   ├── functions.js
|   |   └── index.js
|   ├── less
|   |   ├── global.less
|   |   ├── index.less
|   |   ├── media.less
|   |   └── style.less
|   ├── pug
|   |   ├── includes
|   |   |   └── mixins.pug
|   |   ├── php
|   |   |   ├── index.pug
|   |   |   ├── *.pug
|   |   |   └── *
|   |   |       └── *.pug
|   |   ├── index.pug
|   |   ├── *.pug
|   |   └── *
|   |       └── *.pug
|   ├── index.html
|   ├── index.php
|   ├── *.html
|   ├── *.php
|   ├── *
|   |   └── *.html
|   └── *
|       └── *.php
├── .gitignore
├── .gitlab-ci.yml
├── bs-config.js
├── docker-compose.yml
├── gulpfile.js
└── package.json
  • dist/css/style.all.min.css is CSS styles file. All styles will be compiled to it
  • dist/img is a folder for images. It will be moved as is
  • dist/js/script.all.min.js is JS script file. All scripts will be compiled to it
  • dist/index.html / dist/index.php is main HTML/PHP file
  • dist/**/*.html are other HTML files. Their paths relative to src or src/pug parent folder will be preserved in dist folder
  • dist/**/*.php are other PHP files. Their paths relative to src or src/pug/php parent folder will be preserved in dist folder
  • src/css folder is supposed to be only used as CSS libraries folder
  • src/img folder is used for images. It will be moved as is
  • src/js folder is used for JS scripts
    • src/js/index.js is main file for scripts. All other JS files should be imported to it
    • src/js/functions.js is auxiliary file and supposed to be used for JS functions. All functions necessary in other files should be exported
  • src/less folder is used for LESS styles
    • src/less/global.less is auxiliary LESS file and supposed to be used for global styles
    • src/less/index.less is main file. All other styles should be imported to it
    • src/less/media.less is auxiliary LESS file and supposed to be used for styles for different media types/devices
    • src/less/style.less is primary LESS file for styles
  • src/pug folder is used for Pug files
    • src/pug/includes are auxiliary Pug files and supposed to be used for including, mixins, templates etc. These files will not be compiled by Pug compiler
      • src/pug/includes/mixins.pug is auxiliary Pug file and supposed to be used for mixins
    • src/pug/php are Pug files that will be compiled by Pug compiler and their extension will be changed to .php
      • src/pug/php/index.pug is main Pug file that will become main PHP file
      • src/pug/php/**/*.pug are other Pug files that will be compiled by Pug compiler and their extension will be changed to .php. Their paths relative to src/pug/php folder will be preserved in dist folder
    • src/pug/index.pug is main Pug file that will become main HTML file
    • src/pug/**/*.pug are other Pug files. Their paths relative to src/pug folder will be preserved in dist folder
  • src/index.html is main HTML file
  • src/**/*.html are other HTML files. Their paths relative to src folder will be preserved in dist folder
  • src/index.php is main PHP file
  • src/**/*.php are other PHP files. Their paths relative to src folder will be preserved in dist folder
  • .gitignore is used to ignore files. dist folder is ignored
  • .gitlab-ci.yml is a CI config. Should not be edited in most of cases
  • bs-config.js is a Browsersync settings
  • docker-compose.yml is a Docker Compose config file
  • gulpfile.js is a gulp config. In paths.files variable inside it can be specified files and folders that will be moved to dist folder as is
  • package.json is main file for npm. Project dependencies can be specified inside it

Note: All markup files will be processed in parallel and therefore their relative paths should not be duplicated. Be aware: in the above project structure files src/index.html, src/pug/index.pug and src/index.php, src/pug/php/index.pug do have the same relative paths!

How to get

  1. Download it manually or get it using project-template-loader:

project-template-loader web/npm-php

2. Open `package.json` and change `name` and `version` to the name and version of your project

## How to use

1. Open terminal
2. Go to your project folder
3. Run 

    ``` bash
npm start
to start Docker container with PHP interpreter and local server that will track changes in project files and update browser page (supposed to be used during development)

*or*

``` bash

npm run build-testing

    to get files in `dist` folder ready to deploy to `testing` environment

    *or*

    ``` bash
npm run build-staging
to get files in `dist` folder ready to deploy to `staging` environment

*or*

``` bash

npm run build

    to get files in `dist` folder ready to deploy to production

### Useful tools

#### weinre

weinre is a debugger for web pages, like FireBug (for FireFox) and Web Inspector (for WebKit-based browsers), except it's designed to work remotely, and in particular, to allow debugging of web pages on mobile devices such as a phones.

To enable weinre support (which is enabled in markup index files by default), the following comment should be added to markup:

* in HTML:

    ```html
<!-- weinre -->

  • in Pug:

//- weinre


After that, weinre will be accessible at [http://weinre.dev.gvia.group](http://weinre.dev.gvia.group).

## Workflow

### Local

During developing under local environment all scripts and styles are not minified and source maps are available for them.

By default, project is accessible at [http://localhost:3000](http://localhost:3000) and Browsersync control panel at [http://localhost:3001](http://localhost:3001).

In addition to that, weinre is accessible at [http://weinre.dev.gvia.group](http://weinre.dev.gvia.group).

### Review

All branches except `dev` and `master` are used to review changes live.

These branches will be built and each one will be available under its own environment with unique address.

For each of them weinre is accessible at [http://weinre.dev.gvia.group](http://weinre.dev.gvia.group).

### Testing

Branch `dev` is used to merge all changes and review them. All developers are responsible to merge their changes to `dev` by themselves.

This branch will be built and available under `testing` environment.

Weinre is accessible at [http://weinre.dev.gvia.group](http://weinre.dev.gvia.group).

### Staging

Branch `master` is used to review changes before deploying to production. It should only contain stable versions that are supposed to be released.

This branch will be built and available under `staging` environment.

Weinre is accessible at [http://weinre.dev.gvia.group](http://weinre.dev.gvia.group) with debug id `staging`.

### Production

To deploy to production:
1. Create the following [secret variables](https://git.gvia.group/help/ci/variables/README.md#secret-variables):
  * `HOSTING_PROJECT` - project name on hosting server
  * `HOSTING_PROJECT_URL` - project site URL
2. Ask GitLab administrator to assign the project to specific runner that will deploy the project