PHPackages eriktorsner/wp-bootstrap - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. eriktorsner/wp-bootstrap ActiveWp-cli-package eriktorsner/wp-bootstrap ======================== Utils for bootstrapping a WordPress installation 0.5.2(9y ago)445365[4 issues](https://github.com/eriktorsner/wp-bootstrap/issues)MITPHPPHP >=5.3.9 Since Oct 5Pushed 9y ago4 watchersCompare [ Source](https://github.com/eriktorsner/wp-bootstrap)[ Packagist](https://packagist.org/packages/eriktorsner/wp-bootstrap)[ Docs](https://github.com/eriktorsner/wp-bootstrap/)[ RSS](/packages/eriktorsner-wp-bootstrap/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (4)Versions (39)Used By (0) wp-bootstrap ============ [](#wp-bootstrap) Wp-cli subcommand for managing WordPress installations. Automates installation, configuration and importing/exporting content. The central idea with WP Bootstrap is to provide a tool that makes it easier to create a decent WordPress deployment workflow. WP Bootstrap lets you use configuration files and a few command line commands to install WordPress, set it up with the correct plugins and themes, import options as well as pages, posts, menus etc. To top it of, it also maintains ID integrity during import so that the site looks the same when it's imported as it did when it was exported, even if all the underlying post ID's have changed. Tutorial for pre-subcommand usage (before 0.4.0): [Tutorial on wpessentials.io](http://www.wpessentials.io/2015/12/preparing-a-wordpress-site-for-git-using-wp-bootstrap/) Installation ------------ [](#installation) To add this package as a local, per-project dependency to your project, simply add a dependency on `eriktorsner/wp-bootstrap` to your project's `composer.json` file. Here is a minimal example of a `composer.json` file that just defines a dependency wp-bootstrap: ``` { "require": { "eriktorsner/wp-bootstrap": "~0.5.0" } } ``` or from the command line: ``` $ composer require eriktorsner/Wp-bootstrap ``` Once WP Bootstrap is installed, wp-cli needs to know about it. Find (or create) your wp-cli.yml config file and add: ``` require: - vendor/autoload.php ``` Configuration files ------------------- [](#configuration-files) WP Bootstrap uses configuration files to control the installation of WordPress as well as plugins and themes. FileFormatDescriptionsappsettings.ymlYamlDefines plugins, themes and import/export settings.envDotenvEnvironment variables needed to install WordPress.env-developmentDotenvOptional. Environment variable for the development environment.env-testDotenvOptional. Environment variable for the test environmentwp-cli.ymlYamlThe standard wp-cli config file. Sub command setenv manages path and writes the environment in this fileQuick introduction. Installing and setting up WordPress using WP Bootstrap -------------------------------------------------------------------------- [](#quick-introduction-installing-and-setting-up-wordpress-using-wp-bootstrap) **Step 1: Creating .env files** As a first step, create a .env file in your project root with settings matching your local database and apache/nginx configuration. Note that since WP Bootstrap maintains settings file in the project root folder, it's recommended to install WordPress in different location like a sub folder. ``` # file: .env wppath=/path/to/target/wordpress wpurl=www.example.com dbhost=localhost dbname=wordpress dbuser=wordpress dbpass=secret wpuser=admin wppass=anothersecret ``` Optionally, create an 'overlay' .env file for a specific environment, i.e 'development': ``` # file: .env-development wppath=/path/to/target/wordpress-dev wpurl=dev.example.com dbname=wordpress-dev ``` Update the wp-cli.yml file with path and environment info: ``` $ wp setenv standard ``` Or (if you created a .env-development): ``` $ wp setenv development ``` **Step 2: Create an appsettings.yml file (optional)** Create the appsettings.yml file that defines this WordPress installation ``` # file: appsettings.yml # set a title for the WordPress site (defaults to '[title]') title: Testing Bootstrap # keep default content such as themes, posts, pages etc. keepDefaultContent: true # add a few plugins from the repo plugins: standard: - wp-cfm - disable-comments:1.3 content: posts: page: '*' ``` **Step 3: Install WordPress** Install WordPress ``` $ wp bootstrap Install ``` ...and install plugins etc. ``` $ wp bootstrap setup ``` Once WordPress is up and running, you will typically run the setup command over and over again as you add config to the appsettings.yml **Step 4: Exporting and importing content** To export the content defined: ``` $ wp bootstrap export ``` ... and to import it back again: ``` $ wp bootstrap import ``` To make a quick test. Use the appsettings.yml defined in step 2 above and execute the export command. The defined content (all pages) will be serialized and stored under the bootstrap subfolder in your project root. Edit (or even delete) the default sample page in WordPress and run the import command. The page should then be completely restored. Importing and exporting content ------------------------------- [](#importing-and-exporting-content) The WP Bootstrap export command will take all content defined in appsettings.yml and serialize it to disk. The target folder is 'bootstrap' in your project root. This folder is supposed to be managed in Git so that it can be easily transferred to a another environment. As you might note, not all content in a WordPress installation is exported, actually it's the opposite, as little as possible but enough to maintain a working site. The idea is that you only export the content that you deem are part of you *application* meaning for instance the static front page, the menu structure, all the content in various about pages and terms and conditions and anything similar. When the site is deployed to production, the same content will be imported there. The benefit of this might not be apparent when you deploy the site the first time. But when the site have been live for a few weeks and it's time to overhaul the menu structure and make a few changes to the About Us page, the benefits will become more apparent. At this time the production site might have lots of new blog posts, even more comments and perhaps even e-commerce orders. You don't want to make a complete database migration from your development environment because that would destroy all this other content. But by using WP Bootstrap you can import and overwrite just exactly those pieces of content that are defined in the appsettings.yml file. No other content on the target site gets touched. Besides just exporting and importing content. WP Boostrap does three other things: - It keeps track of the internal integrity of the content. A page with ID 10 in your development environment might end up with ID 223 in the production environment. If you have a menu that points to page ID 10 in the exported content, that menu will be modified to point to ID 223 when it's imported into production. - It keeps track of parent/child relationships. If the exported page with ID 10 is a child page of page 45, page 45 will be included in the exported content as well, otherwise the parent/child relationship would break - It keeps an eye on media. If an exported page uses a featured image and two more images are used in the post content, WP Bootstrap identifies these images and includes them in the exported data. ### Managing WordPress options [](#managing-wordpress-options) WP Bootstrap is tightly integrated with the plugin WP-CFM. It's not mandatory to use it and you'll have to specify WP-CFM manually among the plugins in appsettings.yml. When exporting content, WP Bootstrap will use WP-CFM to export options defined in a WP-CFM bundle named 'wpbootstrap'. The resulting json file is copied to the bootstrap/config sub folder and should be managed under git. At import, that file is copied back into the expected location under wp-content and pushed back into the WordPress database. The actual management of what options to include is managed using the WP-CFM UI in the WordPress admin area. [Read more about WP-CFM here](https://wordpress.org/plugins/wp-cfm/). To help you identify what options to include and which ones that are changed, please refer to the section about the optiosnap command below. Available commands ------------------ [](#available-commands) WP Bootstrap adds the following commands to wp-cli: ### Subcommand bootstrap [](#subcommand-bootstrap) The below commands are executed using: ``` $ wp bootstrap ``` CommandArgumentsDescriptioninstallAdd Wp-Bootstrap bindings to composer.jsonsetupDownload and install WordPress core. Creates a default WordPress installationexportAdd themes and plugins and import contentimportAlias for wp-install followed by wp-setupresetUpdates core, themes or plugins that are installed from the WordPress repository### Subcommand setenv [](#subcommand-setenv) Setenv is a separate command that updates the wp-cli.yml file with settings from the .env files CommandArgumentsDescriptionsetenvUpdates the variables 'path' and 'environment' in wp-cli.yml*Note:* setenv uses the output from wp --info to determine name and location of the project specific wp-cli.yml file ### Subcommand optionsnap [](#subcommand-optionsnap) Optionsnap is a utility that helps you keep track of which WordPress options that are in use in the WordPress installation. It's essentially dumping the contents of the wp\_options table into a file located in sub folder bootstrap/snapshots. It's mainly intended to help developers understand which option values that are modified between two points in time. The below commands are executed using: ``` $ wp optionsnap ``` CommandArgumentsDescriptionsnap <--comment>Creates a new snapshot file with an optional commentlistLists all available snapshotsshowLists alls options values in the snapshot named show <option\_name>Shows the option identified by <option\_name> in the snapshot diffShows the diff between the current state of the wp\_options table the snapshot identified by diff Shows the diff between the two snapshots identified by and Settings -------- [](#settings) ### Dotenv files [](#dotenv-files) Settings that are unique to a specific WordPress installation environment are kept in dotenv files. These settings are only used when installing WordPress for the first time. To make it easier to maintain multiple WordPress installs on the same physical or virtual machine, one dotenv file can overlay the base one. When executing the install command, WP Bootstrap first looks in the wp-cli.yml file to read the name of the current environment. In the next step, it reads the variables contained in the base dotenv file (.env). In the last step, it looks for a file named .env- and if that file exists, it is also read and parsed. For values that are found in both the base and the environment specific file, the value from the environment specific one takes precedence. VariableDescriptionwppathThe path where WordPress should be installed. Also used by setenv to update wp-cli.yml when switching environmentswpurlThe URL for the WordPress installation. Determined by the web server settingsdbhostThe host name for the MySql databasedbnameThe database name for the MySql databasedbuserMySql user namedbpassMySql user passwordwpuserDefault WordPress user name (often 'admin')wppassPassword for the above WordPress user### Application settings [](#application-settings) The Application settings file, appsettings.yml defines WP Bootstraps behavior when installing plugins and themes and when importing and exporting data to and from WordPress. The settings file consists of several sections: #### Base parameters: [](#base-parameters) - **title** Specifies the title/blogname for the new WordPress installation. Used during bootstrap install - **version** (optional). Specifies the WordPress core version to install. If not specified (recommended) the latest version is installed - **keepDefaultContent** (optional). If not set or if set to false, all default content and all themes and plugins are removed after initial installation. To keep the default content, set this parameter to true. #### Plugins [](#plugins) ### Section: plugins [](#section-plugins) This section consists of up to three sub sections named "standard", "local" and "localcopy". In each section, a list of plugins is defined. Plugins that are available in the WordPress plugin repository or via a URL are defined in the "standard" section. Plugins that exists locally in the same Git repository as the project are defined in the "local" section and are linked into the target WordPress install using a symlink. Some plugins won't behave very well as a symlink and they need to be copied into the correct place, these plugins are defined in the "localcopy" section. The "local" and "localcopy" sections are mostly used for premium plugins that can't be installed via the standard WordPress repository. Each of the three plugin sections define a list. In it's simplest form, the list is just a string that identifies the slug of the plugin and an optional version like shown here: ``` plugins: standard: - akismet - woocommerce - google-sitemap-generator:4.0.6 local: - mycustomplugin ``` In some (rare) cases, a plugin can't be installed unless another plugin or theme is already installed. To handle this, the plugin list can also contain an object with some optional extra parameters. To ensure that a specific plugin isn't installed before another one: ``` plugins: standard: - akismet - woocommerce: requires: plugins: ['google-sitemap-generator'] themes: ['mycustomtheme'] - google-sitemap-generator local: - mycustomplugin ``` In this example, the WooCommerce plugin will not be installed until after Google Sitemap Generator and the theme Mycustomthme are installed. For standard plugins, the slug refers to the unique identifier (last part of the URL) in the WordPress repository. If the slug is a full URL, the plugin will be installed from that URL. But for local and localcopy plugins, the slug refers to the folder name that the plugin is stored in on the local file system. The above definition would assume a project file tree that looks something like this: ``` . └── wp-content ├── plugins │   └── mycustomplugin │   ├── file1.php │   └── file2.php └── themes └── mycustomtheme ├── functions.php └── style.css ``` When defining a plugin as an object rather than a simple string. The object can have the following properties: - **slug** The name/slug of the plugin (will override the key name used in the list) - **version** Specifying a version when installing a plugin from the official WordPress repository, - **requires** Two lists of slugs identifying other themes and plugins that needs to be installed first - **plugins** An array of slugs (string) that defines required plugins - **themes** An array of slugs (string) that defines required themes ### Section: themes [](#section-themes) Similar to the plugins section but for themes. The only real difference is that the themes section also has the parameter 'active' that identifies the theme that should be activated. - **standard** Fetches themes from the official WordPress repository. If a specific version is needed, specify the version using a colon and the version identifier i.e **footheme:1.1** - **local** A list of themes in your local project folder. The themes are expected to be located in folder projectroot/wp-content/themes/. Local themes are symlinked into place in the wp-content folder of the WordPress installation specified by wppath in localsettings.json - **localcopy** A list of themes in your local project folder. The themes are expected to be located in folder projectroot/wp-content/themes/. Local themes are copied into place in the wp-content folder of the WordPress installation specified by wppath in localsettings.json. Some poorly written themes and plugins requires to be located in the correct WordPress folder, but consider it as a last option - **active** A string specifying what theme to activate. ### Section: settings [](#section-settings) A list of options (settings) that will be applied to the WordPress installation using the wp-cli command "option update %s". Currently only supports simple scalar values (strings and integers). Example: ``` settings: admin_email: foobar@example.com blogname: My first blog blogdescription: Just anohter blog tagline ``` For the most part, it's recommended to manage options using the WP-CFM plugin. WP Bootstrap has build in support for importing and exporting options using WP-CFM. Managing options directly in the appsettings.yml can quickly become overwhelming. ### Section: content [](#section-content) This sections defines how to handle content during export and import of data using the wp-export or wp-import command. **posts** Used during the export process. Contains zero or more keys with an associated array. The key specifies a post\_type (page, post etc) and the array contains **post\_name** for each post to include. The export process also includes any media (images) that are attached to the specific post or are referred to in the post content or post meta. **menus** Used during the export process. Contains zero or more keys with an associated array. The key represents the menu name (as defined in WordPress admin) and the array should contain each *location* that the menu appears in. Note that location identifiers are unique for each theme. **taxonomies** Used during the export process. Contains zero or more keys with either a string or array as the value. Use asterisk (\*) if you want to include all terms in the taxonomy. Use an array of term slugs if you want to only include specific terms from that taxonomy. ### Section: references [](#section-references) Used during the import process. This is a structure that describes option values (in the wp\_option table) that contains references to a page or a taxonomy term. The reference item can contain a "posts" and a "terms" object describing settings that points to either posts or taxonomy terms. Each of these objects contains one single member "options" referring to the wp\_options table (support for other references will be added later). The "options" member contains an array with names of options in the wp\_option table. There are three ways to refer to an option: - **1.** A simple string, for instance "page\_on\_front". Meaning that there is an option in the wp\_options table named "page\_on\_front" and that option is a reference to a post ID. - **2.** An object with a single name-value pair, for instance {"mysetting": "\[2\]"} or {"mysetting2":"->page\_id"} meaning: - There is an option in the wp\_options table named "mysetting" - That setting is an array or object and the value tells wp-bootstrap how to access the array element or member variable of interest. The value follows PHP syntax, so an array element is accessed via "\[\]" notation and an object member variable is accessed via the "->" syntax. - **3.** As above, but instead of a simple string value, the value is an array of strings. Reference resolving will only look at the pages/posts/terms included in your import set. The import set might include an option "mypage" in the config/wpbootstrap.json file that points to post ID=10. Also in the import set, there is that page with id=10. When this page is imported in the target WordPress installation, it might get another ID, 22 for instance. By telling wp-bootstrap that the setting "mypage" in the wp\_options table refers to a page, wp-bootstrap will update that option to the new value 22 as part of the process. ### Section: extensions [](#section-extensions) If the basic functionality in Wp-Bootstrap can't handle content in a certain situation, it's often possible to handle it via an extension. An extension is a PHP class that implements WordPress filters and actions to respond to certain events. For instance, if a plugin uses a custom table, an extension can hook into the 'wp-bootstrap\_after\_export' action to serialize that table to a file when the site is being exported. During import, the extension would hook into the 'wp-bootstrap\_after\_import' action to read the serialized file back into the database. Extensions can be made specifically for a certain plugin or for a specific site project. NameTypeDescriptionwp-bootstrap\_before\_importActionCalled before all import activitieswp-bootstrap\_after\_import\_settingsActionCalled after settings have been imported with WP-CFMwp-bootstrap\_after\_import\_contentActionCalled after content (posts, menus etc) have been importedwp-bootstrap\_after\_importActionCalled after all import activities are donewp-bootstrap\_before\_exportActionCalled before any export activities startswp-bootstrap\_after\_exportActionCalled after all exports activities are donewp-bootstrap\_option\_post\_referencesFilterLets the extension add names of option values that refer to a post id.wp-wp-bootstrap\_option\_term\_referencesFilterLets the extension add names of option values that refer to a term idTo use an extension, WP Bootstrap must be able to autoload the class. The easiest way to achieve this is to add a PSR4 namespace to the composer.json file of your project: ``` { "require": { "eriktorsner/wp-bootstrap": "~0.4.0" }, "autoload": { "psr-4": { "MyNamespace\\": "src" } } ``` Then place your extension in the sub folder "src" (relative to the project root). Any extension classes will be instantiated at the beginning of the process and a method "init" will be called. In this method the extension can add filters and actions that will be executed in various stages in the installation/import process: ```