{"id":18615630,"url":"https://github.com/hex-digital/acf-migrations","last_synced_at":"2025-10-10T09:36:21.348Z","repository":{"id":95868234,"uuid":"53867392","full_name":"hex-digital/acf-migrations","owner":"hex-digital","description":"An easy way to migrate local fields and field groups using readable object oriented syntax (without the need for huge arrays)","archived":false,"fork":false,"pushed_at":"2020-10-01T10:11:21.000Z","size":42,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-27T03:12:27.446Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hex-digital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2016-03-14T15:18:34.000Z","updated_at":"2020-10-01T10:11:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"23d83e6f-f8eb-4860-8e9f-f5f1fc43f51c","html_url":"https://github.com/hex-digital/acf-migrations","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex-digital%2Facf-migrations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex-digital%2Facf-migrations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex-digital%2Facf-migrations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex-digital%2Facf-migrations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hex-digital","download_url":"https://codeload.github.com/hex-digital/acf-migrations/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239406497,"owners_count":19633025,"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":[],"created_at":"2024-11-07T03:30:57.697Z","updated_at":"2025-10-10T09:36:16.300Z","avatar_url":"https://github.com/hex-digital.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# acf-migrations\n\n### Quick Start\n```bash\ntouch acf/migrations.php \u0026\u0026 echo \"\u003c?php $migrations = new Migrations;\" \u003e\u003e acf/migrations.php\necho 'acf/export.php' \u003e\u003e .gitignore\n```\n\nThen add following code to `functions.php`\n\n```bash\n$acf_export_file = __DIR__ . '/acf/export.php';\nif ( file_exists( $acf_export_file ) ) include $acf_export_file;\n```\n\n### Description\n\nAn easy way to migrate local fields and field groups using readable object oriented syntax (without the need for huge arrays).\n\nBy converting 113 lines to just 20 by using this easy-to-use class, you can dramatically reduce your development time and increase your workflow.\n\n![Screenshot](https://cloud.githubusercontent.com/assets/9773040/13950509/495e53dc-f023-11e5-81cc-2ef836cf65fd.png)\n\n### Set up\n\nSimply create a directory in your theme called `acf` and add a `migrations.php` file containing the `example.php.dist` code. Once activated, the plugin will automatically generate the local Advanced Custom Fields code to be added to your project.\n\nBe sure to add `acf/export.php` to your `.gitignore` file since this will not need to be added if you can run the generated executable upon deployment of your website.\n\nAfter installing the plugin and successfully generating your fields, add the following code to your `functions.php` file:\n\n    $acf_export_file = __DIR__ . '/acf/export.php';\n    if ( file_exists( $acf_export_file ) ) include $acf_export_file;\n\n### The executable\n\nFor deployments, it makes sense to have a single executable file that can run independently. To download this executable upon deployment, simply use curl:\n\n    curl -o acf-migrations.phar https://raw.githubusercontent.com/hex-digital/acf-migrations/master/acf-migrations.phar\n\nYou can then use the acf-migrations.phar (much like [Composer](https://getcomposer.org)) to generate your Advanced Custom Field code:\n\n    php acf-migrations.phar -t /var/www/vhosts/example.com/wp-content/themes/my-theme\n\nWhere the `-t` flag is the template directory of your WordPress website.\n\n### How to use\n\n#### Prerequisite - ACF Playground Process\n\nPrior to writing ACF migrations, it's advised to gain some knowledge in what the export file looks like. To do this, have a play around with creating fields in the Custom Fields -\u003e Field Groups section like normal. Once you have created several example ACF configurations, please head to Custom Fields -\u003e Tools, check the example field groups then click Generate PHP. Please make key observations of the different array items that make up each type of field as this will come handy when creating complex field group configurations.\n\nThis playground process will help you define well defined custom fields via the migrations file.\n\n#### Adding a field group\n\nNow you have a general idea of what array items make up a field configuration, let's look at adding our first field.\nHead over to `acf/migrations.php` and see if any existing fields exist. If so, great! You can use them as a template for adding further fields. If not, no worries, let's add one.\n\nYou'll first notice the `Migrations` object has been instanced (`$migrations`). To add a field group, add the following.\n\n```php\n$migrations-\u003eaddFieldGroup('Our staff', [\n    [\n        'param' =\u003e 'post_type',\n        'operator' =\u003e '==',\n        'value' =\u003e 'page',\n    ],\n], [\n    'hide_on_screen' =\u003e ['content_editor']\n])\n```\n\nThere are a few things to note here. Firstly, the key `Our staff` is simply the name of the field group. Secondaly, you'll\nnotice the array of page type binding arrays. In this example, the field group will display on any `page` post type. If you\nwant the field group to show on multiple post types, add another binding array to the configurations like so.\n\n```php\n    [\n        'param' =\u003e 'post_type',\n        'operator' =\u003e '==',\n        'value' =\u003e 'page',\n    ],\n    [\n        'param' =\u003e 'post_type',\n        'operator' =\u003e '==',\n        'value' =\u003e 'staff',\n    ],\n```\n~Note: You can bind field groups to custom post types.~\n\n#### Adding a field\n\nNow that we have a field group, we want to add fields. To see what types of fields you can add, please refer to the [field types](https://www.advancedcustomfields.com/resources/#field-types) documentation. To create a field, add the following shortly after the newly created field group.\n\n```php\n    -\u003eaddField('text', 'Full name')\n```\n\nThis will create a simple text field with the label `Full name`. This name is used to create the key of the field which is required when\ntrying to display the fields content on within templates or method code. The key generated is a snake case key so our example would become `full_name`.\n\nIf you want to find a the accepted field type values, you can again refer to generated export code via the playground process.\n\nNote: the example above will apply the default configurations values for a text field. If you would like to add extra configurations to the field, please add like so\n\n```php\n    -\u003eaddField('text', 'Full name', [\n        'instructions' =\u003e 'Add a full name for the staff member.',\n    ])\n```\n\nThere are many extra configurations that can be added to fields so please play around in the export playground as stated in the prerequisite to find the key =\u003e value pairs for these settings. The example below shows a well configured image field.\n\n```php\n    -\u003eaddField(\n        'image',\n        'Thumbnail',\n        [\n            'instructions' =\u003e 'Please add an image. Max width: 300px',\n            'return_format' =\u003e 'array',\n            'preview_size' =\u003e 'thumbnail',\n            'min_width' =\u003e 50,\n            'min_height' =\u003e 50,\n            'min_size' =\u003e '',\n            'max_width' =\u003e 300,\n            'max_height' =\u003e 300,\n            'max_size' =\u003e '0.5',\n            'mime_types' =\u003e 'jpg, jpeg',\n        ]\n    )\n```\n\n#### Repeater fields \u0026 Sub fields\n\nIt is common to have a field that contains sub-fields which can be repeated. This is known as [repeater fields](https://www.advancedcustomfields.com/resources/repeater/). To create this type of field, add a repeater type field like so\n\n```php\n    -\u003eaddField(\n        'repeater',\n        'Award Items',\n        [\n            'layout' =\u003e 'block',\n            'instructions' =\u003e 'Please add award items',\n            'button_label' =\u003e 'Add Item',\n        ]\n    )\n```\n\nNow we have the repeater field setup, we can add sub-fields using the `addSubField()` method.\n\n```php\n        -\u003eaddSubField(\n            'text',\n            'Award Title',\n            0,\n            [\n                'instructions' =\u003e 'Add a title for the award.',\n            ]\n        )\n```\n\nNotice that this method accepts the same type, name and configuration array parameters as the `addField` method. The only difference being the `depth` parameter which is an integer outlining the depth of the sub-field. In our example, the sub-field is at the first level under the main fields so the depth is set to 0. If, for example, you nest another repeater within, you will need to increase the depth of it's repsective sub-field parameters accordingly. Below is an example of nested repeater fields.\n\n```php\n    -\u003eaddField(\n        'repeater',\n        'Items',\n        [\n            'layout' =\u003e 'block',\n            'instructions' =\u003e 'Please add block items',\n        ]\n    )\n        -\u003eaddSubField(\n            'text',\n            'Item title',\n            0\n        )\n        -\u003eaddSubField(\n            'repeater',\n            'Item Logos',\n            0,\n            [\n                'layout' =\u003e 'block',\n                'instructions' =\u003e 'Please add item logos',\n            ]\n        )\n            -\u003eaddSubField(\n                'image',\n                'Logo',\n                1\n            );\n```\n\n#### Flexible layouts\n\nBeside field groups, field and sub-fields, we can also add [flexible layouts](https://www.advancedcustomfields.com/resources/flexible-content/) which provide a simple, structured, block-based editor. To add flexible content first add a `flexible_content` field.\n\n```php\n-\u003eaddField(\n    'flexible_content',\n    'Content Blocks',\n    [\n        'button_label' =\u003e 'Add Block',\n    ]\n)\n```\n\nNow we have added the base field, we now need to define layout types. Do so by adding a `addLayout` method.\n\n```php\n    -\u003eaddLayout(\n        'media_block',\n        'Media Block'\n    )\n```\n\nNotice that unlike `addField` or `addSubField` methods, the key and name parameter are seperate in this method.\nFinally, we can now add fields to the layout by using the sub-field method.\n\n```php\n    -\u003eaddSubField(\n        'text',\n        'Title',\n        0\n    )\n    -\u003eaddSubField(\n        'image',\n        'Media Item',\n        0\n    )\n```\n\n#### How to use guidance\n\nAs long as your syntax isn't breaking the export file from being created, and you know how to use these `addFieldGroup`, `addField`, `addSubField` and `addLayout` methods correctly, you should be able to create well validated and easy-to-use custom fields. If at anytime you are struggling to add any configurated fields, please play around with the ACF Playground Process.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhex-digital%2Facf-migrations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhex-digital%2Facf-migrations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhex-digital%2Facf-migrations/lists"}