|
1 | | -## changelog |
| 1 | +# WP-CLI for Advanced Custom Fields |
2 | 2 |
|
3 | | -- Removed uniqid feature (no longer needed). |
4 | | -- Bugfix: database fieldgroups are now prefered over exported fieldgroups. |
5 | | -- Cleaned up legacy xml import/export libraries. |
6 | | -- Add namespaces. |
7 | | -- Cleaned up all alternative notation uses. |
8 | | -- Multisite now correctly makes use of the global --url parameter. |
9 | | -- Added more comments and versioning. |
10 | | -- Removed dependency of wp-importer. |
11 | | -- Added support for composer installs. |
12 | | -- Dropped XML support, hello Json. |
13 | 3 |
|
| 4 | +### Description |
14 | 5 |
|
15 | | -# WP-CLI for Advanced Custom Fields |
| 6 | +WP-CLI for Advanced Custom Fields helps you manage your field-groups through WP-CLI. |
| 7 | +The reason we started this project is to make life easier for developers working on Wordpress projects using the Advanced Custom Fields Pro plugin. |
| 8 | +Fields can now easily be imported, exported and shared over SVN, GIT or comparable systems. |
16 | 9 |
|
17 | | -This extension for Advanced Custom Fields that makes it possible to manage your `field-groups` through the console of [wp-cli](http://wp-cli.org/). The goal of this project is to make life easier for developers who working on Wordpress projects that use Advanced Custom Fields and love the WP-CLI command line tools. |
| 10 | +## Installation |
18 | 11 |
|
19 | 12 |
|
20 | | -## Reasons to start this project |
| 13 | +### Requirements |
21 | 14 |
|
22 | | -* Advanced custom fields did not interface with WP-CLI |
23 | | -* Sharing `field-groups` through XML or PHP code caused problems with differences between development, test, staging and production enviroments when shared with XML. |
24 | | -* No direct SVN or GIT support without manually putting the exported PHP or XML into a versioned directory. |
25 | | -* Naming convention for XML files was always the same, resulting in renaming hassle. |
26 | | -* Only using the generated `field-groups` on runtime through PHP code in `functions.php` disables the editing mode (which is an awesome UI that we require). So importing should be possible. |
| 15 | +* Advanced Custom Fields 5 Pro plugin |
| 16 | +* `wp-cli` http://wp-cli.org/ |
27 | 17 |
|
28 | | -## Requirements |
29 | 18 |
|
30 | | -* Advanced Custom Fields plugin |
31 | | -* `wp-cli` http://wp-cli.org/ |
| 19 | +### How to install |
| 20 | + |
| 21 | +Install WP-CLI as described on [http://wp-cli.org/](http://wp-cli.org/ "WP-CLI") |
| 22 | + |
| 23 | +Using composer: |
| 24 | +``` |
| 25 | +composer require wpackagist-plugin/advanced-custom-fields-wpcli |
| 26 | +``` |
| 27 | + |
| 28 | +By GIT clone in plugins directory: |
| 29 | +``` |
| 30 | +git clone https://github.com/hoppinger/advanced-custom-fields-wpcli.git |
| 31 | +``` |
| 32 | + |
| 33 | +WordPress plugin installation: |
| 34 | +Download zip and put the files in the plugins directory. |
| 35 | + |
| 36 | +* Activate this plugin in the plugin menu or using: |
| 37 | +``` |
| 38 | +wp plugin activate advanced-custom-fields-wpcli |
| 39 | +``` |
| 40 | + |
| 41 | +Go the wordpress directory in your terminal and run: |
| 42 | +``` |
| 43 | +wp acf |
| 44 | +``` |
| 45 | +To see if everything is working correctly. |
32 | 46 |
|
| 47 | +When the plugin is enabled, any exported field groups found on the filesystem in your registered paths will be added to Wordpress at runtime. |
| 48 | +If you would like to disable this behaviour you can remove the `acf_wpcli_register_groups` action: |
| 49 | +``` |
| 50 | +remove_action('plugins_loaded', 'acf_wpcli_register_groups'); |
| 51 | +``` |
33 | 52 |
|
34 | | -## Commands |
| 53 | +## Commands |
35 | 54 |
|
36 | 55 | This project adds the `acf` command to `wp-cli` with the following subcommands: |
37 | 56 |
|
38 | | -* `wp acf`: Default test and prints the help overview. |
39 | | -* `wp acf status`: provides a list of found `field-groups` in the current database of your Wordpress project. |
40 | | -* `wp acf export`: |
41 | | - * creates a `field-group` directory into your current theme's directory. |
42 | | - * creates a directory with the `field-group` name for each fieldgroup. |
43 | | - * creates a `data.php` and `data.json` for each `field-group` inside their respective folders. |
44 | | - * use `wp acf export --all` to export everything without prompting |
45 | 57 |
|
46 | | -* `wp acf import`: imports the JSON(s) from `active-theme`/field-groups/{field-group_name}/data.json` |
47 | | - * When using wp acf import a selection menu apears to choose which field-group to import |
| 58 | +### Help |
| 59 | +``` |
| 60 | +wp acf |
| 61 | +``` |
| 62 | +Prints the help overview and can be used as a default test to see if the plugin is working. |
| 63 | +``` |
48 | 64 |
|
49 | | -* `wp acf clean`: cleans up the database from all found ACF post types and their coupled `post_meta` values, use this after you've edited the `field-groups` in the UI and used export to generate the new `data.php` files. Watch out: __cannot__ be undone. |
50 | 65 |
|
| 66 | +### Export |
51 | 67 |
|
52 | | -## How to use |
| 68 | +Export a field-group to a json file in the directory set by a filter. |
| 69 | +``` |
| 70 | +wp acf export |
| 71 | +``` |
53 | 72 |
|
54 | | -1. install `wp-cli` http://wp-cli.org/ |
55 | | -2. clone this repo as `advanced-custom-fields-wpcli` in your plugins directory |
56 | | -3. activate `advanced-custom-fields-wpcli` plugin through "wp plugin activate advanced-custom-fields-wpcli" (or activate in the plugin menu) |
57 | | -4. open a terminal and go to your wordpress directory |
58 | | -5. type `wp` (and see the `acf` commands if installed correctly) |
59 | | -6. type `wp acf` to test the `acf-wpcli` extension |
60 | | -7. start using the commands as explained in "Commands" |
| 73 | +You want to export all field-groups all at once you can use: |
| 74 | +``` |
| 75 | +wp acf export --all |
| 76 | +``` |
61 | 77 |
|
62 | | -When the plugin is enabled, any exported field groups found on the filesystem in your registered paths will be added to Wordpress at runtime. |
63 | 78 |
|
64 | | -If you would like to disable this behaviour you can remove the `acf_wpcli_register_groups` action: |
65 | | -```php |
66 | | - remove_action('plugins_loaded', 'acf_wpcli_register_groups'); |
| 79 | +### Import |
| 80 | +``` |
| 81 | +wp acf import |
67 | 82 | ``` |
| 83 | +Import all or specific fields from a option menu, |
68 | 84 |
|
69 | | -### Filters |
70 | 85 |
|
71 | | -* acfwpcli_fieldgroup_paths |
72 | | - By default ACF-CLI will search 2 paths for field-groups. The active_theme and active_child_theme. |
73 | | - The acfwpcli_fieldgroup_paths gives you the ability to add more paths where ACF-CLI should load/export from/to. |
74 | | - Example: |
75 | | -```php |
76 | | - add_filter( 'acfwpcli_fieldgroup_paths', 'add_plugin_path' ); |
| 86 | +### Clean |
| 87 | +``` |
| 88 | +wp acf clean |
| 89 | +``` |
| 90 | +Delete all Advanced Custom Fields Records from the database. |
| 91 | +Do this after you have edited fields-groups from the UI and exported the changes. |
| 92 | +**Warning: This can not be undone, please use carefully** |
| 93 | +
|
| 94 | +## Filters |
| 95 | +
|
| 96 | +
|
| 97 | +### acfwpcli_fieldgroup_paths |
| 98 | +
|
| 99 | +The acfwpcli_fieldgroup_paths gives you the ability to add more paths where ACF-CLI should load/export from/to. |
| 100 | +You should always add at least one path to this filter. |
| 101 | +
|
| 102 | +``` |
| 103 | +add_filter( 'acfwpcli_fieldgroup_paths', 'add_plugin_path' ); |
77 | 104 |
|
78 | | - public function add_plugin_path( $paths ) { |
79 | | - $paths['my_plugin'] = MY_PLUGIN_ROOT . '/lib/field-groups/'; |
80 | | - return $paths; |
81 | | - } |
| 105 | +public function add_plugin_path( $paths ) { |
| 106 | + $paths['my_plugin'] = MY_PLUGIN_ROOT . '/lib/field-groups/'; |
| 107 | + return $paths; |
| 108 | +} |
82 | 109 | ```` |
83 | 110 |
|
84 | | -## TODOs |
| 111 | +## Unit testing |
| 112 | +
|
| 113 | +To test changes to the plugin you can use unit testing. Start by making sure all the necessary dependencies are installed, if not run: |
| 114 | +``` |
| 115 | +composer install |
| 116 | +``` |
| 117 | +
|
| 118 | +You will need a new Wordpress installation to make sure the tests run |
| 119 | +independent from your Wordpress installation and database. To create a wordpress installation for testing run the following command: |
| 120 | +``` |
| 121 | +bash bin/test_wp_install.sh wordpress_test db_username db_password localhost latest |
| 122 | +``` |
| 123 | +
|
| 124 | +Where 'wordpress_test' is the name for the database used to run the tests. Make sure this database doesn't exist or can be deleted. When the database |
| 125 | +already exists the script will ask you if the database can be deleted. 'Latest' can be changed if you want to test with a specific version of Wordpress, 3.6.2 for example. |
| 126 | +
|
| 127 | +After you installed you can start running tests using the follow command: |
| 128 | +``` |
| 129 | +vendor/bin/behat |
| 130 | +``` |
| 131 | +
|
| 132 | +This will run all test. These tests include an import and export of all types of fields, cleaning, multiple fields in one field-group and tests for |
| 133 | +the menu options. If you want to run one specific test you can do this by running: |
| 134 | +``` |
| 135 | +vendor/bin/behat features/testname.feature |
| 136 | +``` |
| 137 | +
|
| 138 | +If you need a different test you can create your own by added it to the features in the features folder. |
| 139 | +
|
| 140 | +## Upgrade Notice |
| 141 | +
|
| 142 | +
|
| 143 | +### 3.0 |
| 144 | +* Make sure you import all your custom fields before updating. |
| 145 | +* Make sure you are you using ACF5, ACF4 is not supported. |
| 146 | +* Update the plugin |
| 147 | +* Add the filter to your project (See Filters) |
| 148 | +* Export you fields |
| 149 | +* Remove unnecessary files like your old import directory, php files and json files. |
| 150 | +
|
| 151 | +## Changelog |
| 152 | +
|
| 153 | +
|
| 154 | +### 3.0 |
| 155 | +* Bugfix: Import no longer created duplicates |
| 156 | +* Add unit testing with behat and PHPUnit |
| 157 | +
|
85 | 158 |
|
86 | | -* make `acf-wpcli` extension update-proof |
87 | | -* release this plugin as official WordPress plugin |
| 159 | +### 2.0 |
| 160 | +* Removed uniqid feature (no longer needed). |
| 161 | +* Bugfix: database fieldgroups are now prefered over exported fieldgroups. |
| 162 | +* Cleaned up legacy xml import/export libraries. |
| 163 | +* Add namespaces. |
| 164 | +* Cleaned up all alternative notation uses. |
| 165 | +* Multisite now correctly makes use of the global --url parameter. |
| 166 | +* Added more comments and versioning. |
| 167 | +* Removed dependency of wp-importer. |
| 168 | +* Added support for composer installs. |
| 169 | +* Dropped XML support, hello Json. |
0 commit comments