{"id":15396025,"url":"https://github.com/luizbills/wp-plugin-base","last_synced_at":"2025-04-16T00:16:30.411Z","repository":{"id":53832938,"uuid":"487076969","full_name":"luizbills/wp-plugin-base","owner":"luizbills","description":"Powerful opinated boilerplate for WordPress plugins :electric_plug:","archived":false,"fork":false,"pushed_at":"2024-12-05T14:04:57.000Z","size":334,"stargazers_count":13,"open_issues_count":6,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-16T00:16:11.982Z","etag":null,"topics":["classicpress","composer","php","wordpress","wordpress-boilerplate","wordpress-development","wordpress-plugin"],"latest_commit_sha":null,"homepage":"https://github.com/luizbills/wp-plugin-base","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luizbills.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"luizbills","custom":"https://www.luizpb.com/donate/"}},"created_at":"2022-04-29T18:41:53.000Z","updated_at":"2024-12-05T14:05:02.000Z","dependencies_parsed_at":"2023-09-26T23:27:12.495Z","dependency_job_id":"8c8377c3-ae3f-4400-be47-11b15ab57b08","html_url":"https://github.com/luizbills/wp-plugin-base","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizbills%2Fwp-plugin-base","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizbills%2Fwp-plugin-base/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizbills%2Fwp-plugin-base/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizbills%2Fwp-plugin-base/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luizbills","download_url":"https://codeload.github.com/luizbills/wp-plugin-base/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249173094,"owners_count":21224484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["classicpress","composer","php","wordpress","wordpress-boilerplate","wordpress-development","wordpress-plugin"],"created_at":"2024-10-01T15:30:29.980Z","updated_at":"2025-04-16T00:16:30.389Z","avatar_url":"https://github.com/luizbills.png","language":"PHP","funding_links":["https://github.com/sponsors/luizbills","https://www.luizpb.com/donate/"],"categories":[],"sub_categories":[],"readme":"## WP Plugin Base\n\nPowerful Boilerplate for WordPress Plugins.\n\n## Requirements\n\n- [PHP](http://php.net/) v7.4+\n- [Git](https://git-scm.com/downloads)\n- [Composer](https://getcomposer.org/download/) (globally installed as `composer`)\n- [WP-CLI](https://wp-cli.org/#installing) (optional; only needed to generate the `.pot` file)\n\n## Install\n\nOpen your terminal and execute the script below in your `wp-content/plugins` to generate a new plugin:\n\n```bash\nwp_plugin_base_clone_dir=\".wp_plugin_base_$(date +%s)\" \\\n\u0026\u0026 git clone --branch main --single-branch --no-tags --quiet \\\n  https://github.com/luizbills/wp-plugin-base.git $wp_plugin_base_clone_dir \\\n\u0026\u0026 cd $wp_plugin_base_clone_dir \u0026\u0026 php .installer/install.php \u0026\u0026 sleep .1 \\\n\u0026\u0026 cd $(cat install.log) \\\n\u0026\u0026 chmod -R +x ./scripts \\\n\u0026\u0026 rm -rf \"../$wp_plugin_base_clone_dir\"\n```\n\n## Upgrade\n\nYou can update the `core` folder of your plugin running the command `composer run upgrade-core`.\n\n## Getting started\n\nThis boilerplace is organized into several files and folders. It is essential that you understand each of them.\n\n### `/main.php`\n\nThis is the main plugin file with its headers (plugin name, version, license, etc). Open the file and fill in some remaining information, like the `Plugin URI` and `Description`.\n\nIf you want to keep translation files inside your plugin, you should uncomment the `load_plugin_textdomain` function.\n\n### `/config.php`\n\nIn this file you can declare useful (and immutable) values that will be used in different places in the plugin. By default, values like the plugin's **SLUG** and **PREFIX** will already be declared (you can change them if you want, but you can't delete them).\n\nInternally, the plugin will also declare the following keys:\n- `NAME`: The plugin name.\n- `VERSION`: The plugin version.\n- `FILE`: The main file absolute path (`/main.php`).\n- `DIR`: The plugin folder absolute path.\n\nTo get these values, you should use the `config_get` helper:\n\n```php\nuse Your_Namespace\\Helpers as h;\n\n// example: print your plugin name\necho h::config_get( 'NAME' );\n```\n\n### `/dependencies.php`\n\nIn this file you must inform what your plugin needs to work. By default, the plugin will already check the server's PHP version (v7.4 or later).\n\nEach dependency is an array that must contain the following keys:\n- `check`: a function that should check if any requirements have been met.\n- `message`: a string (or function that returns a string) that will be displayed if the requirement is not met.\n\nExample: use the following code below to indicate that your plugin depends on the WooCommerce plugin to work.\n\n```php\n$deps[] = [\n\t'check' =\u003e function () {\n\t\t// checks if the `WooCommerce` class exists\n\t\t// that class only exists when the WooCommerce plugin is active.\n\t\treturn class_exists( 'WooCommerce' );\n\t},\n\n\t// the message that will be shown if WooCommerce plugin is not activated.\n\t'message' =\u003e 'This plugin depends on WooCommerce plugin to works.'\n];\n```\n\nIf any dependencies are missing, the plugin will not work and a notice will be shown in the admin panel informing the reason (with the messages you declared).\n\nOpen the [/dependencies.php](/dependencies.php) to learn more.\n\n### `/loader.php`\n\nThis file should return a array of classes that you want to run automatically, when the plugin is ready to work (if all dependencies in the `/dependencies.php` file are satisfied).\n\nEach index in the array can be a class name or an array (with the class name and an integer to indicate priority). By default, each class has priority 10.\n\nExample:\n```php\n// loader.php\nreturn [\n\tMy_Class_1::class, // priority = 10\n\t[ My_Class_2::class, 20 ], // priority = 20\n\t[ My_Class_3::class, 5 ], // priority = 5\n];\n```\n\nIn the example above, the classes will run in the following order: `My_Class_2` then `My_Class_1` and finally `My_Class_3`. Classes with higher priority are executed first.\n\n### `/uninstall.php`\n\nThis file is automatically executed when your plugin is deleted. Use it to clean the database (if your plugin saved anything).\n\n### `/core` folder\n\nThis folder has the core of our boilerplace (classes that initialize the plugin, check dependencies, load classes from `/loader.php`, etc). You don't need to understand the core classes, but you can take a look, it's all pretty simple.\n\nThe `/core/VERSION` file stores the boilerplate version. So you can update the files in the core folder using the `composer run upgrade-core` command (without having to do it manually).\n\n### `/classes` folder\n\nIn this folder you will put the classes that control all features of your plugin: custom post types, settings pages, shortcodes, etc.\n\nIf you put a class in the `/loader.php` file, its `__start` method will be executed automatically when the plugin is ready to work. See the [`classes/Sample_Class.php`](classes/Sample_Class.php) to more details.\n\n**NOTE:** You don't need to add all your classes in `/loader.php`. Only add the classes that need to run some code automatically or to listen WordPress actions and filters hooks.\n\n### The `Helpers` class\n\nThe [`classes/Helpers.php`](/classes/Helpers.php) file contains several static methods that can be very useful in developing your plugin. To make it easier, I recommend that at the beginning of each class file you include `use Your_Namespace\\Helpers as h;` to work as a shortcut `h` for the `Helpers` class.\n\n**NOTE:** The `Helpers` class is not used in the boilerplace core, so you can modify or even delete it without any problem.\n\nTake a look at some helper methods that you will enjoy using.\n\n#### ➞ `h::config_get( $key, $default = null )`\n\nReturns the values ​​you declared in the `/config.php` file. The first argument is the key and the second is a default value that will be returned if the key does not exist. However, if you don't want to declare a default value, the plugin will throw an exception (to help avoid typos).\n\n#### ➞ `h::config_set( $key, $value )`\n\nTemporarily save values, an alternative to global variables (no need to worry about prefixes). To get the saved values, just use `h::config_get`.\n\n#### ➞ `h::get_defined( $constant, $default = null )`\n\nChecks whether a constant (declared with `define` or `const` in a class) exists and returns its value. If it doesn't exist, returns a default value (the second argument, which is `null` by default).\n\n#### ➞ `h::filled( $var )`\n\nReturns `false` ONLY IF $var is `null`, `empty array`, `empty object` or `empty string`.\n\n**Note:** `h::filled` works differently than `empty`.\n\n```php\nuse Your_Namespace\\Helpers as h;\n\nh::filled( null ); // false\nh::filled( [] ); // false (empty array)\nh::filled( new \\stdClass() ); // false (empty class)\nh::filled( \"\" ); // false (empty string)\nh::filled( \"     \" ); // false (strings are trimmed)\nh::filled( false ); // true (it is filled with a boolean)\nh::filled( 0 ); // true (it is filled with a number)\n\n// ... Any other values ​​returns TRUE\n```\n\n#### ➞ `h::prefix( $string, $sanitize = true )`\n\nPrepends the plugin PREFIX (defined in `/config.php`) in the `$string`. By default, the `$string` is sanitized (only numbers, letters and underlines)`.\n\n```php\nuse Your_Namespace\\Helpers as h;\n\necho h::prefix( 'foo bar baz' ) // \"your_prefix_foo_bar_baz\"\necho h::prefix( 'foo bar baz', false ) // \"your_prefix_foo bar baz\"\n```\n\n#### ➞ `h::dd( ...$vars )`\n\nUseful to quick debug something. This helper will print all arguments with `var_dump` and immediately stop PHP execution with `die( 1 )`.\n\n```php\nh::dd( $var ) // print the $var content and exit\n```\n\n#### ➞ `h::log( ...$vars )`\n\nUseful to quick logs something in `debug.log` (if your `WP_DEBUG` and `WP_DEBUG_LOG` are enabled).\n\n```php\nuse Your_Namespace\\Helpers as h;\n\nh::log( $var ) // logs the $var in wp-content/debug.log by default\n```\n\n#### ➞ `h::throw_if( $condition, $message, $class = \\Error::class )`\n\nIf the `$condition` is falsy, throws a exception (by default a `\\Error` instance) with the `$message`.\n\n```php\nuse Your_Namespace\\Helpers as h;\n\nh::throw_if(\n\tis_null( $my_var ),\n\t'My exception message'\n);\n\n// it is the same as\nif ( is_null( $my_var ) ) {\n\tthrow new \\Error( 'My exception message' );\n}\n\n// also, you can use other exception classes (3rd argument)\nh::throw_if(\n\tis_null( $my_var ),\n\t'My exception message',\n\tYour_Namespace\\CustomException::class,\n);\n```\n\n#### Other helpers\n\nSee the [`/core/Traits`](/core/Traits) folder to learn the helpers. They are all very simple codes to read and understand. If you think some that helpers could be even simpler, please [open an issue](https://github.com/luizbills/wp-plugin-base/issues/new).\n\n### `/assets` folder\n\nPut your frontend stuffs there: JavaScript, CSS, images ...\n\n### `/.wordpress-org` folder\n\nPut WordPress SVN repository stuffs there: Plugin icon, banner and screenshots.\n\n**NOTE:** If you are not planning to publish your plugin, you can delete this folder.\n\n### `/scripts` folder\n\nThis folder contains some scripts that are used in the commands explained below:\n\n- `composer run make-pot` creates a `.pot` file inside of `/languages` directory.\n- `composer run build` creates a `.zip` file inside of `/wp-build` directory. Easy way to share or install your plugin on other WordPress.\n- `composer run upgrade-core` will update the `/core` folder of your plugin, pulling the latest changes from this Github repository.\n- `composer run deploy` updates your SVN repository and release a new version on https://wordpress.org (you need setup the [`/scripts/svn-push`](/scripts/svn-push) file first). This script also update your plugin assets (icon, banner and screenshot) when necessary in the `/.wordpress-org` directory.\n- `composer run update-trunk` updates the `/trunk` of your SVN repository on https://wordpress.org (you need setup the [`/scripts/svn-push`](/scripts/svn-push) file first). This script also update your plugin assets (icon, banner and screenshot) when necessary in the `/.wordpress-org` directory.\n\n## Recommended Tools\n\n- [CPT Model](https://gist.github.com/luizbills/b030beeff64380d300afa16670fde022)\n- [Git Updater](https://github.com/afragen/git-updater)\n- [PostTypes](https://github.com/jjgrainger/PostTypes/)\n- [Carbon Fields](https://carbonfields.net)\n- [WP Customizer Framework](https://github.com/inc2734/wp-customizer-framework/)\n\n## Contributing\n\n- [Create an issue](https://github.com/luizbills/wp-plugin-base/issues/new) for questions, suggestions or bugs.\n\n## LICENSE\n\nThis repository is licensed under [MIT](https://choosealicense.com/licenses/mit/).\n\nThe generated plugin source code will have [GPLv3](/LICENSE) by default (feel free to change).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluizbills%2Fwp-plugin-base","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluizbills%2Fwp-plugin-base","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluizbills%2Fwp-plugin-base/lists"}