10up / plugin-scaffold Goto Github PK

DEPRECATED. Use https://github.com/10up/wp-scaffold

License: GNU General Public License v2.0

PHP 55.46% JavaScript 38.79% CSS 5.75%

plugin-scaffold's Introduction

10up Plugin Scaffold

DEPRECATED. Use https://github.com/10up/wp-scaffold

At 10up, we strive to provide digital products that yield a top-notch user experience. In order to improve both our efficiency and consistency, we need to standardize what we use and how we use it. This plugin scaffold allows us to share initial set up procedures to make sure all projects can get up and running as quickly as possible while closely adhering to 10up's high quality standards.

Dependencies

Node >= 8.11 & NPM - Build packages and 3rd party dependencies are managed through NPM, so you will need that installed globally.
Webpack - Webpack is used to process the JavaScript, CSS, and other assets.
Composer - Composer is used to manage PHP.

Getting Started

Quick Start

Install 10up's command line tool for scaffolding new projects. You can download it from the Project Scaffold repository. Setting up a new plugin is as easy as running create-10up plugin plugin-name-here in the terminal!

Browsersync requires a local development URL. This is currently set in the package.json, as proxyUrl.

Direct Install

Clone the repository
Rename folder plugin-scaffold -> your project's name
If copying files manually to an existing plugin directory instead of cloning directly from the repository, make sure to include the following files which may be hidden:

.babelrc
.browserslistrc
.editorconfig
.eslintignore
.eslintrc
.gitignore

The NPM commands will fail without these files present.

Do case-sensitive search/replace for the following:
- TenUpScaffold
- TENUP_SCAFFOLD
- tenup-scaffold
- tenup_scaffold
cd into the plugin folder
run npm run start to build the front-end assets

Webpack config

Webpack config files can be found in config folder:

webpack.config.dev.js
webpack.config.common.js
webpack.config.prod.js
webpack.settings.js

In most cases webpack.settings.js is the main file which would change from project to project. For example adding or removing entry points for JS and CSS.

NPM Commands

npm run test (runs phpunit)
npm run start (install dependencies)
npm run watch (watch)
npm run build (build all files)
npm run build-release (build all files for release)
npm run dev (build all files for development)
npm run lint-release (install dependencies and run linting)
npm run lint-css (lint CSS)
npm run lint-js (lint JS)
npm run lint-php (lint PHP)
npm run lint (run all lints)
npm run format-js (format JS using eslint)
npm run format (alias for npm run format-js)
npm run test-a11y (run accessibility tests)

Composer Commands

composer lint (lint PHP files)

composer lint-fix (lint PHP files and automatically correct coding standard violations)

Contributing

We don't know everything! We welcome pull requests and spirited, but respectful, debates. Please contribute via pull requests on GitHub.

Fork it!
Create your feature branch: git checkout -b feature/my-new-feature
Commit your changes: git commit -am 'Added some great feature!'
Push to the branch: git push origin feature/my-new-feature
Submit a pull request

Learn more about the default packages used with this project

Frequently Asked Questions

A question that someone might have

An answer to that question.

Support Level

Active: 10up is actively working on this, and we expect to continue work for the foreseeable future including keeping tested up to the most recent version of WordPress. Bug reports, feature requests, questions, and pull requests are welcome.

Like what you see?

plugin-scaffold's People

Contributors

Stargazers

Watchers

plugin-scaffold's Issues

Import CSS

Hello,

I'm trying to use your plugin with Full Calendar JS (https://fullcalendar.io)

I'm following this guide : https://fullcalendar.io/docs/initialize-es6

For javascript part it's ok.

But for CSS, i have problem :

In admin.js, I add the following code :

import '@fullcalendar/core/main.css';
import '@fullcalendar/daygrid/main.css';

And I have this error :

ERROR in ./node_modules/@fullcalendar/core/main.css 1:0
Module parse failed: Unexpected character '@' (1:0)
You may need an appropriate loader to handle this file type.
> @charset "UTF-8";
| .fc {
|   direction: ltr;
 @ ./assets/js/admin/admin.js 2:0-37

ERROR in ./node_modules/@fullcalendar/daygrid/main.css 4:0
Module parse failed: Unexpected token (4:0)
You may need an appropriate loader to handle this file type.
| --------------------------------------------------------------------------------------------------*/
| /* day row structure */
> .fc-dayGridWeek-view .fc-content-skeleton,
| .fc-dayGridDay-view .fc-content-skeleton {
|   /* there may be week numbers in these views, so no padding-top */
 @ ./assets/js/admin/admin.js 3:0-40

Do I need to do something ? I need to add a config ?

Thanks.

Add normalize via npm to the build

@dainemawer whenever you have time, just making sure the plugin and theme are in sync.

Missing path constant

Hi,

I noticed that in a recent commit (Port Webpack to the plugin) the path returned by the script_url() function in the core.php file is missing the TENUP_SCAFFOLD_URL prefix, which will prevent the scripts from being loaded.

plugin-scaffold/includes/functions/core.php

Line 103 in 32ec736

return "dist/js/${script}.js";

Addind back the TENUP_SCAFFOLD_URL prefix fixed the issue. I hope this could be helpful and that I didn't miss anything in the webpack config.

Cryptic errors when get_enqueue_contexts 'fails'

Describe the bug
If you modify the array that the get_enqueue_contexts method returns, a new WP_Error object is created and returned when performing the in_array check in several methods. This causes a somewhat cryptic error being thrown as at that point you are attempting to enqueue a script or stylesheet with a WP_Error object as the style/script path string.

Steps to Reproduce

Clone the repo
Run npm run-script start, yarn start, etc.
Remove admin from return [ 'admin', 'frontend', 'shared' ]; on line 86 of core.php
Activate the plugin

Expected behavior
Display a WordPress warning/error on the back-end with the messages passed to the WP_Error constructors.

Screenshots

Catchable fatal error: Object of class WP_Error could not be converted to string in /var/www/html/wp-includes/http.php on line 681 
...

Deprecated WP_Mock calls

dave@DESKTOP-BT7RIFJ /mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test (master) $ vendor/bin/phpunit
PHPUnit 6.5.7 by Sebastian Bergmann and contributors.

.R.RR                                                               5 / 5 (100%)

Time: 3.03 seconds, Memory: 10.00MB

There were 3 risky tests:

1) TenUp\GeneratorTest\Core\Core_Tests::test_i18n
Deprecated WP Mock calls inside :
  WP_Mock::wpFunction ["get_locale","Array([3] ...)"]
                      ["load_textdomain","Array([2] ...)"]
                      ["plugin_basename","Array([3] ...)"]
                      ["load_plugin_textdomain","Array([2] ...)"]

/mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test/vendor/10up/wp_mock/php/WP_Mock/DeprecatedListener.php:33
/mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test/vendor/10up/wp_mock/php/WP_Mock/Tools/TestCase.php:314
/mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test/vendor/10up/wp_mock/php/WP_Mock/Tools/TestCase.php:307
/mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test/tests/phpunit/test-tools/TestCase.php:13

2) TenUp\GeneratorTest\Core\Core_Tests::test_activate
Deprecated WP Mock calls inside :
  WP_Mock::wpFunction ["flush_rewrite_rules","Array([1] ...)"]

/mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test/vendor/10up/wp_mock/php/WP_Mock/DeprecatedListener.php:33
/mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test/vendor/10up/wp_mock/php/WP_Mock/Tools/TestCase.php:314
/mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test/vendor/10up/wp_mock/php/WP_Mock/Tools/TestCase.php:307
/mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test/tests/phpunit/test-tools/TestCase.php:13

3) TenUp\GeneratorTest\Core\Core_Tests::test_deactivate
This test did not perform any assertions

/mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test/vendor/10up/wp_mock/php/WP_Mock/Tools/TestCase.php:307
/mnt/c/Users/dave/Code/wp-local-docker/wordpress/wp-content/plugins/generator-test/tests/phpunit/test-tools/TestCase.php:13

OK, but incomplete, skipped, or risky tests!
Tests: 5, Assertions: 4, Risky: 3.

Add Husky Pre-Commit Hooks for JS Linting

@nicholasio Same deal as this PR to keep the repos in sync: 10up/theme-scaffold#35

Install Webpack and Gulp

Set up initial webpack and gulp from the theme scaffold

Fatal Error: Cannot redeclare style_url() within mce_css()

PHP is throwing a fatal error on L:227 of functions/core.php when mce_css filter is being run. On the post edit screen for example.

Steps to reproduce

Scaffold a new plugin: create-10up plugin my-fancy-plugin
Activate the plugin: wp plugin activate my-fancy-plugin
Attempt to create a new post or page.

Environment

WP 4.9.5
PHP 7.2.1
Chrome

Front-end styles in a plugin?

I'm probably missing something but why are we using front-end styles like normalize.css from the plugin? For all use cases I can think of these should be in a theme only.

Add linting command for CSS

Do the same linting command as in theme-scaffold.

Inline global declarations in the config files generate eslint errors.

10up/theme-scaffold#180

Clean Up the Root

With the new webpack conversion we have a /config directory set up. Any config files, linting, processing, etc that can be moved out of the root and into the /config directory should be to clean up the root of the project.

Related theme issue: 10up/theme-scaffold#137

Examples of autoloading and namespacing classes?

The example composer.json has

"autoload": { "psr-4": { "TenUpScaffold\\": "includes/classes/" } }

But then there is no example inside the includes/classes/ folder of how to namespace different classes, nor differet example namespaces in the composer.json file, and have them all autoloaded with psr-4.

Would it be possible to include a simple example of how to include classes under different namespaces like, eg,

TenUpScaffold\ClassOne, TenUpScaffold\AnotherClass, TenUpScaffold\AnotherOne\Helper ?

Would be great to see in the sample class how it is initialized, etc.

Thank you for your scaffold repos!

Using error_log in production

We are using error log to indicate when trying to load a script or style with a context that is not recognized. Usually, error_log would be flagged in a code review as not belonging in production.

I am wondering the reasoning behind this decision and wondering if there is not another way to indicate this as this will only be used during development and only appear if adding another context or typoing the existing ones.

Understanding the above, that this won't be fired in production, I am wondering if we should wrap this in a WP_DEBUG check with a comment for any engineers using this as a learning resource.

Add feature/prefers-reduced-motion to scaffolding

Initially referenced on slack here:
https://10up.slack.com/archives/C10CPMBD2/p1547741052016500

Add header fields to plugin.php and readme.txt files

Is your enhancement related to a problem? Please describe.
The WordPress.org plugin headers and readme.txt standards appear to have evolved a bit and our scaffold files should likely include some additional fields.

Describe the solution you'd like

add Requires PHP, License, License URI to readme.txt
add sample FAQ question+answer to readme.txt as the .org format is not intuitive
add 10up logo as a sample for banner, icon, and screenshot to avoid null view on .org
add 10up sample screenshot to readme.txt as the .org format is not intuitive
add Requires at least, Requires PHP, License, License URI to plugin.php

Designs

n/a

Describe alternatives you've considered

Maybe we consider the fuller list of PHPDoc DoclBlock's as noted here as well?: https://developer.wordpress.org/plugins/plugin-basics/header-requirements/#header-fields

Additional context

Plugin Readmes: https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/
Header Requirements: https://developer.wordpress.org/plugins/plugin-basics/header-requirements/

Feature: replace LiveReload with Browsersync

There is currently an Issue open with Theme Scaffold, as well as an associated Pull Request.

All discussion and context is there, and mostly just wanted to open and assign a ticket as a reminder to get this in the Plugin Scaffold.

Standardize the enqueue contexts

Keeping the script and style enqueue contexts inside of the helper methods used to generate the URL requires updating code in multiple places when adding a new item. This can be simplified by adding a helper function.

readme updates

It's not obvious the level of support provided for this repo, so let's add some clarification.

add support level section and badge
add license file and badge

Add new core template function

From: 10up/theme-scaffold#114

Upgrade to Gulp 4

Upgrade Gulp version to 4 to sync with the theme repo: 10up/theme-scaffold#4

Error Activating Plugin

Noting this here for later review (i.e. so I can close this browser tab):

`( ! ) Fatal error: Uncaught Error: Call to undefined function TenUp\GeneratorTest\Core\setup() in /var/www/html/wp-content/plugins/generator-test/plugin.php on line 28
( ! ) Error: Call to undefined function TenUp\GeneratorTest\Core\setup() in /var/www/html/wp-content/plugins/generator-test/plugin.php on line 28
Call Stack

Time Memory Function Location

1 0.0069 481480 {main}( ) .../plugins.php:0
2 3.8195 22619264 plugin_sandbox_scrape( ) .../plugins.php:172
3 3.8238 22623408 include( '/var/www/html/wp-content/plugins/generator-test/plugin.php' ) .../plugin.php:1897
`

Media Queries in CSS not compiling

Provide the same change requested here - 10up/theme-scaffold#162 (comment)

PR - #112

NPM install: found 705 vulnerabilities (692 low, 13 high)

When I run npm install, I get this message:

found 705 vulnerabilities (692 low, 13 high)
  run `npm audit fix` to fix them, or `npm audit` for details

Is your enhancement related to a problem? Please describe.

Describe the solution you'd like

update packages.

Designs

Describe alternatives you've considered

Additional context

I use windows 10 pro.
nvm using node v.12.17.0

Switch to Webpack

From: 10up/theme-scaffold#111

Update eslint with package

Use this: https://www.npmjs.com/package/@10up/eslint-config

Same issue is on the theme

Add browserlist to the NPM packages

https://github.com/browserslist/browserslist

SVGs are cropped upon deployment

Describe the bug
When npm run build is run, SVGs have their "viewbox" attribute removed which causes cropping:

This is caused in plugin-scaffold/config/webpack.config.common.js. ImageminPlugin can be updated to this to correct it:

		// Compress images
		// Must happen after CopyWebpackPlugin
		new ImageminPlugin({
			disable: !isProduction,
			test: settings.ImageminPlugin.test,
			svgo: {
				plugins: [
					{
						removeViewBox: false,
					},
				],
			},
		}),

Steps to Reproduce

If you site has SVGs, run npm run build to see the cropping
npm run watch does not include the cropping because ImageminPlugin is disabled on non-production environments,.

Expected behavior
No cropping

Add Composer information to README.md

Please make sure this PR 10up/theme-scaffold#54 makes its way into the plugin repo as well. Thanks!

Updated gulp task to require Autoprefixer

Sync with theme: 10up/theme-scaffold#46

Add static analysis

Is your enhancement related to a problem? Please describe.
Many problems in the PHP code could not be discovered by humans.

Describe the solution you'd like
Introduce @phpstan (as Automattic and Google already did)

Describe alternatives you've considered
There is no better static analysis then PHPStan.

Additional context
It needs a WordPress Extension.

composer.lock should not be in .gitignore

composer.lock file should be committed to our projects so that when we deploy them, we can run composer install and get a very specific set of package versions installed.

I could see maybe not wanting a composer.lock file in the scaffold repo, but we definitely want it in the repos that are generated as part of the scaffolding.

Fatal error in post editor

Action:

Edit a page in wp-admin

Expected:

No php errors

Instead:

I see this error:

Fatal error: Cannot redeclare Facebook\Elearning\Plugin\Core\style_url() 
(previously declared in /srv/www/fbelearning/public_html/wp-content/plugins/fb-elearning/includes/functions/core.php:115) 
in /srv/www/fbelearning/public_html/wp-content/plugins/fb-elearning/includes/functions/core.php 
on line 261

core.php contains these two snippets:

https://github.com/10up/plugin-scaffold/blob/master/includes/functions/core.php#L98

function style_url( $stylesheet, $context ) {
	if( !in_array( $context, ['admin', 'frontend', 'shared'], true) ) {
		error_log('Invalid $context specfied in TenUpScaffold stylesheet loader.');
		return '';
	}
	return ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ?
		TENUP_SCAFFOLD_URL . "assets/css/${context}/{$stylesheet}.css" :
		TENUP_SCAFFOLD_URL . "dist/css/${stylesheet}.min.css" ;
}

https://github.com/10up/plugin-scaffold/blob/master/includes/functions/core.php#L225

function mce_css( $stylesheets ) {

	function style_url() {

		return FB_ELEARNING_PLUGIN_URL . ( ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ?
			"assets/css/frontend/editor-style.css" :
			"dist/css/editor-style.min.css" );

	}

	return $stylesheets . ',' . style_url();
}

Suggested fix

Possibly the second instance of style_url() should be an anonymous function?

Upgrade to Babel 7

Add async/defer tags for enqueueing scripts

From 10up/theme-scaffold#77

PHPUnit test not working

Getting this error

Fatal error: Declaration of WP_Mock\Tools\TestCase::setUp() must be compatible with PHPUnit\Framework\TestCase::setUp():

Prefers-reduced-motion update

Per this comment on twitter:
https://twitter.com/scottjehl/status/1086287082031583232?s=11

.. we should change the style to be the following (more stable / reliable):
`@media (prefers-reduced-motion: reduce) {

*,
*::before,
*::after {
	animation-duration: 0.1s !important;
            transition-duration: 0.1s !important;
}

Add assets for WordPress.org deployment via GitHub Actions

Is your enhancement related to a problem? Please describe.
We are seeing increased usage of our GitHub Actions for deploying plugins to WordPress.org, and with the GA for Actions slated for mid-November and this being a “template” repo, I think it makes sense to go ahead and add what’s necessary for GitHub Actions to this repo so we’re ready from the jump. See 10up/action-wordpress-plugin-deploy#11 as well.

Describe the solution you'd like
Add .github/workflows/tag-deploy.yml, .github/workflows/asset-readme-update.yml, .distignore, and .wordpress-org/README.md. The last one should contain the image types, sizes, and naming that WordPress.org looks for, which I think makes more sense than bundling images that might unwittingly be deployed and avoids the empty directory in Git issue.

Designs
n/a

Describe alternatives you've considered
n/a

Additional context
I will work on a PR here within the next couple weeks unless somebody else wants to claim it first.

Require vendor/autoload by default

After playing around with the plugin scaffold a little bit, and asking Darshan for some insight, it became apparent that using require_once 'vendor/autoload.php'; is detrimental to autoloading classes. This ticket may just be a lack of experience from my side, but is there any reason why the requiring of autoload.php is not added to the plugin architecture by default?