[5.x] Dictionaries

[duncanmcclean]

This pull request introduces the concept of Dictionaries to Statamic.

The Dictionary fieldtype works in a similar way to the Select fieldtype. However, the main difference is that the options are returned from a PHP class (called a "dictionary"), instead of being defined in the field's config.

There's a few common use cases where this is helpful:

• When you have a YAML or JSON file with options, but you don't want to enter the options into a Select field manually.
• When the options are coming from an external API of some kind. Previously, you'd need to build your own relationship fieldtype for this.
• Probably others that I haven't thought of yet...

Available Dictionaries

Statamic includes a few helpful dictionaries right out of the box:

• Countries
• Currencies
• Timezones

Building your own dictionary

It's really easy to build your own dictionary...

1. Generate a dictionary class using php please:

    php please make:dictionary Provinces

   If you want to generate a dictionary for an addon, use the --addon parameter.

2. In your app/Dictionaries directory (or src/Dictionaries in an addon), you'll see your new Provinces dictionary has been generated:

   class Provinces extends Dictionary
   /** * Returns a key/value array of options. * * @param string|null $search * @return array */
   public functionoptions(?string$search = null): array
   {
   return$this->getItems()
   ->when($search ?? false, function ($collection) use ($search) {
   return$collection->filter(fn ($item) => str_contains($item['name'], $search));
   })
   ->mapWithKeys(fn ($item) => [$item['slug'] => $item['name']])
   ->all();
   }
   /** * Returns a single option. * * @param string $key * @return string|array */publicfunctionget(string$key): string|array
   {
   return$this->getItems()->firstWhere('slug', $key);
   }
   privatefunctiongetItems(): Collection
   {
   returncollect([
   ['name' => 'January', 'slug' => 'january'],
   ['name' => 'February', 'slug' => 'february'],
   ['name' => 'March', 'slug' => 'march'],
   // ...
   ]);
   } }

   • The options method should return a key/value array of all options.
     • The $search variable will be provided if the user is searching options. Feel free to search the options in whatever way works for you.
   • The get method should return a single option.
     • This will be made available when the dictionary field's options are augmented. You're free to return whatever you need here.
   • Optionally, you can also configure "config fields" for the dictionary which will be available in the dictionary's context:

   protectedfunctionfieldItems()
   {
   return [
   'region' => [
   'display' => __('Region'),
   'instructions' => __('statamic::messages.dictionaries_countries_region_instructions'),
   'type' => 'select',
   'options' => $this->getCountries()->unique('region')->pluck('region', 'region')->filter()->all(),
   ],
   ];
   }
   publicfunctionget(string$key): string|array
   {
   $region = $this->context['region'];
   // ...
   }

[jasonvarga]

I've made a whole bunch of tweaks. The initial description of this PR is fairly outdated now. The docs PR is the most up to date source now. statamic/docs#1405

tl;dr:

• Added an opinionated BasicDictionary subclass that devs can extend, making custom dictionaries way simpler. Basically just need to define an array of items.
• Added a File dictionary, letting users grab a JSON or YAML file from somewhere, throw into their app, and then they can have a custom dictionary without writing any PHP. (It should be trivial to support other file types later like xml, csv, etc)

[duncanmcclean]

This pull request introduces the concept of Dictionaries to Statamic.

The Dictionary fieldtype works in a similar way to the Select fieldtype. However, the main difference is that the options are returned from a PHP class (called a "dictionary"), instead of being defined in the field's config.

There's a few common use cases where this is helpful:

• When you have a YAML or JSON file with options, but you don't want to enter the options into a Select field manually.
• When the options are coming from an external API of some kind. Previously, you'd need to build your own relationship fieldtype for this.
• Probably others that I haven't thought of yet...

Available Dictionaries

Statamic includes a few helpful dictionaries right out of the box:

• Countries
• Currencies
• Timezones

Building your own dictionary

It's really easy to build your own dictionary...

1. Generate a dictionary class using php please:

    php please make:dictionary Provinces

   If you want to generate a dictionary for an addon, use the --addon parameter.

2. In your app/Dictionaries directory (or src/Dictionaries in an addon), you'll see your new Provinces dictionary has been generated:

   class Provinces extends Dictionary
   /** * Returns a key/value array of options. * * @param string|null $search * @return array */
   public functionoptions(?string$search = null): array
   {
   return$this->getItems()
   ->when($search ?? false, function ($collection) use ($search) {
   return$collection->filter(fn ($item) => str_contains($item['name'], $search));
   })
   ->mapWithKeys(fn ($item) => [$item['slug'] => $item['name']])
   ->all();
   }
   /** * Returns a single option. * * @param string $key * @return string|array */publicfunctionget(string$key): string|array
   {
   return$this->getItems()->firstWhere('slug', $key);
   }
   privatefunctiongetItems(): Collection
   {
   returncollect([
   ['name' => 'January', 'slug' => 'january'],
   ['name' => 'February', 'slug' => 'february'],
   ['name' => 'March', 'slug' => 'march'],
   // ...
   ]);
   } }

   • The options method should return a key/value array of all options.
     • The $search variable will be provided if the user is searching options. Feel free to search the options in whatever way works for you.
   • The get method should return a single option.
     • This will be made available when the dictionary field's options are augmented. You're free to return whatever you need here.
   • Optionally, you can also configure "config fields" for the dictionary which will be available in the dictionary's context:

   protectedfunctionfieldItems()
   {
   return [
   'region' => [
   'display' => __('Region'),
   'instructions' => __('statamic::messages.dictionaries_countries_region_instructions'),
   'type' => 'select',
   'options' => $this->getCountries()->unique('region')->pluck('region', 'region')->filter()->all(),
   ],
   ];
   }
   publicfunctionget(string$key): string|array
   {
   $region = $this->context['region'];
   // ...
   }

[jasonvarga]

I've made a whole bunch of tweaks. The initial description of this PR is fairly outdated now. The docs PR is the most up to date source now. statamic/docs#1405

tl;dr:

• Added an opinionated BasicDictionary subclass that devs can extend, making custom dictionaries way simpler. Basically just need to define an array of items.
• Added a File dictionary, letting users grab a JSON or YAML file from somewhere, throw into their app, and then they can have a custom dictionary without writing any PHP. (It should be trivial to support other file types later like xml, csv, etc)

[duncanmcclean]

This pull request introduces the concept of Dictionaries to Statamic.

The Dictionary fieldtype works in a similar way to the Select fieldtype. However, the main difference is that the options are returned from a PHP class (called a "dictionary"), instead of being defined in the field's config.

There's a few common use cases where this is helpful:

• When you have a YAML or JSON file with options, but you don't want to enter the options into a Select field manually.
• When the options are coming from an external API of some kind. Previously, you'd need to build your own relationship fieldtype for this.
• Probably others that I haven't thought of yet...

Available Dictionaries

Statamic includes a few helpful dictionaries right out of the box:

• Countries
• Currencies
• Timezones

Building your own dictionary

It's really easy to build your own dictionary...

1. Generate a dictionary class using php please:

    php please make:dictionary Provinces

   If you want to generate a dictionary for an addon, use the --addon parameter.

2. In your app/Dictionaries directory (or src/Dictionaries in an addon), you'll see your new Provinces dictionary has been generated:

   class Provinces extends Dictionary
   /** * Returns a key/value array of options. * * @param string|null $search * @return array */
   public functionoptions(?string$search = null): array
   {
   return$this->getItems()
   ->when($search ?? false, function ($collection) use ($search) {
   return$collection->filter(fn ($item) => str_contains($item['name'], $search));
   })
   ->mapWithKeys(fn ($item) => [$item['slug'] => $item['name']])
   ->all();
   }
   /** * Returns a single option. * * @param string $key * @return string|array */publicfunctionget(string$key): string|array
   {
   return$this->getItems()->firstWhere('slug', $key);
   }
   privatefunctiongetItems(): Collection
   {
   returncollect([
   ['name' => 'January', 'slug' => 'january'],
   ['name' => 'February', 'slug' => 'february'],
   ['name' => 'March', 'slug' => 'march'],
   // ...
   ]);
   } }

   • The options method should return a key/value array of all options.
     • The $search variable will be provided if the user is searching options. Feel free to search the options in whatever way works for you.
   • The get method should return a single option.
     • This will be made available when the dictionary field's options are augmented. You're free to return whatever you need here.
   • Optionally, you can also configure "config fields" for the dictionary which will be available in the dictionary's context:

   protectedfunctionfieldItems()
   {
   return [
   'region' => [
   'display' => __('Region'),
   'instructions' => __('statamic::messages.dictionaries_countries_region_instructions'),
   'type' => 'select',
   'options' => $this->getCountries()->unique('region')->pluck('region', 'region')->filter()->all(),
   ],
   ];
   }
   publicfunctionget(string$key): string|array
   {
   $region = $this->context['region'];
   // ...
   }

[jasonvarga]

I've made a whole bunch of tweaks. The initial description of this PR is fairly outdated now. The docs PR is the most up to date source now. statamic/docs#1405

tl;dr:

• Added an opinionated BasicDictionary subclass that devs can extend, making custom dictionaries way simpler. Basically just need to define an array of items.
• Added a File dictionary, letting users grab a JSON or YAML file from somewhere, throw into their app, and then they can have a custom dictionary without writing any PHP. (It should be trivial to support other file types later like xml, csv, etc)

[duncanmcclean]

This pull request introduces the concept of Dictionaries to Statamic.

The Dictionary fieldtype works in a similar way to the Select fieldtype. However, the main difference is that the options are returned from a PHP class (called a "dictionary"), instead of being defined in the field's config.

There's a few common use cases where this is helpful:

• When you have a YAML or JSON file with options, but you don't want to enter the options into a Select field manually.
• When the options are coming from an external API of some kind. Previously, you'd need to build your own relationship fieldtype for this.
• Probably others that I haven't thought of yet...

Available Dictionaries

Statamic includes a few helpful dictionaries right out of the box:

• Countries
• Currencies
• Timezones

Building your own dictionary

It's really easy to build your own dictionary...

1. Generate a dictionary class using php please:

    php please make:dictionary Provinces

   If you want to generate a dictionary for an addon, use the --addon parameter.

2. In your app/Dictionaries directory (or src/Dictionaries in an addon), you'll see your new Provinces dictionary has been generated:

   class Provinces extends Dictionary
   /** * Returns a key/value array of options. * * @param string|null $search * @return array */
   public functionoptions(?string$search = null): array
   {
   return$this->getItems()
   ->when($search ?? false, function ($collection) use ($search) {
   return$collection->filter(fn ($item) => str_contains($item['name'], $search));
   })
   ->mapWithKeys(fn ($item) => [$item['slug'] => $item['name']])
   ->all();
   }
   /** * Returns a single option. * * @param string $key * @return string|array */publicfunctionget(string$key): string|array
   {
   return$this->getItems()->firstWhere('slug', $key);
   }
   privatefunctiongetItems(): Collection
   {
   returncollect([
   ['name' => 'January', 'slug' => 'january'],
   ['name' => 'February', 'slug' => 'february'],
   ['name' => 'March', 'slug' => 'march'],
   // ...
   ]);
   } }

   • The options method should return a key/value array of all options.
     • The $search variable will be provided if the user is searching options. Feel free to search the options in whatever way works for you.
   • The get method should return a single option.
     • This will be made available when the dictionary field's options are augmented. You're free to return whatever you need here.
   • Optionally, you can also configure "config fields" for the dictionary which will be available in the dictionary's context:

   protectedfunctionfieldItems()
   {
   return [
   'region' => [
   'display' => __('Region'),
   'instructions' => __('statamic::messages.dictionaries_countries_region_instructions'),
   'type' => 'select',
   'options' => $this->getCountries()->unique('region')->pluck('region', 'region')->filter()->all(),
   ],
   ];
   }
   publicfunctionget(string$key): string|array
   {
   $region = $this->context['region'];
   // ...
   }

[jasonvarga]

I've made a whole bunch of tweaks. The initial description of this PR is fairly outdated now. The docs PR is the most up to date source now. statamic/docs#1405

tl;dr:

• Added an opinionated BasicDictionary subclass that devs can extend, making custom dictionaries way simpler. Basically just need to define an array of items.
• Added a File dictionary, letting users grab a JSON or YAML file from somewhere, throw into their app, and then they can have a custom dictionary without writing any PHP. (It should be trivial to support other file types later like xml, csv, etc)

[duncanmcclean]

This pull request introduces the concept of Dictionaries to Statamic.

The Dictionary fieldtype works in a similar way to the Select fieldtype. However, the main difference is that the options are returned from a PHP class (called a "dictionary"), instead of being defined in the field's config.

There's a few common use cases where this is helpful:

• When you have a YAML or JSON file with options, but you don't want to enter the options into a Select field manually.
• When the options are coming from an external API of some kind. Previously, you'd need to build your own relationship fieldtype for this.
• Probably others that I haven't thought of yet...

Available Dictionaries

Statamic includes a few helpful dictionaries right out of the box:

• Countries
• Currencies
• Timezones

Building your own dictionary

It's really easy to build your own dictionary...

1. Generate a dictionary class using php please:

    php please make:dictionary Provinces

   If you want to generate a dictionary for an addon, use the --addon parameter.

2. In your app/Dictionaries directory (or src/Dictionaries in an addon), you'll see your new Provinces dictionary has been generated:

   class Provinces extends Dictionary
   /** * Returns a key/value array of options. * * @param string|null $search * @return array */
   public functionoptions(?string$search = null): array
   {
   return$this->getItems()
   ->when($search ?? false, function ($collection) use ($search) {
   return$collection->filter(fn ($item) => str_contains($item['name'], $search));
   })
   ->mapWithKeys(fn ($item) => [$item['slug'] => $item['name']])
   ->all();
   }
   /** * Returns a single option. * * @param string $key * @return string|array */publicfunctionget(string$key): string|array
   {
   return$this->getItems()->firstWhere('slug', $key);
   }
   privatefunctiongetItems(): Collection
   {
   returncollect([
   ['name' => 'January', 'slug' => 'january'],
   ['name' => 'February', 'slug' => 'february'],
   ['name' => 'March', 'slug' => 'march'],
   // ...
   ]);
   } }

   • The options method should return a key/value array of all options.
     • The $search variable will be provided if the user is searching options. Feel free to search the options in whatever way works for you.
   • The get method should return a single option.
     • This will be made available when the dictionary field's options are augmented. You're free to return whatever you need here.
   • Optionally, you can also configure "config fields" for the dictionary which will be available in the dictionary's context:

   protectedfunctionfieldItems()
   {
   return [
   'region' => [
   'display' => __('Region'),
   'instructions' => __('statamic::messages.dictionaries_countries_region_instructions'),
   'type' => 'select',
   'options' => $this->getCountries()->unique('region')->pluck('region', 'region')->filter()->all(),
   ],
   ];
   }
   publicfunctionget(string$key): string|array
   {
   $region = $this->context['region'];
   // ...
   }

[jasonvarga]

I've made a whole bunch of tweaks. The initial description of this PR is fairly outdated now. The docs PR is the most up to date source now. statamic/docs#1405

tl;dr:

• Added an opinionated BasicDictionary subclass that devs can extend, making custom dictionaries way simpler. Basically just need to define an array of items.
• Added a File dictionary, letting users grab a JSON or YAML file from somewhere, throw into their app, and then they can have a custom dictionary without writing any PHP. (It should be trivial to support other file types later like xml, csv, etc)

[duncanmcclean]

This pull request introduces the concept of Dictionaries to Statamic.

The Dictionary fieldtype works in a similar way to the Select fieldtype. However, the main difference is that the options are returned from a PHP class (called a "dictionary"), instead of being defined in the field's config.

There's a few common use cases where this is helpful:

• When you have a YAML or JSON file with options, but you don't want to enter the options into a Select field manually.
• When the options are coming from an external API of some kind. Previously, you'd need to build your own relationship fieldtype for this.
• Probably others that I haven't thought of yet...

Available Dictionaries

Statamic includes a few helpful dictionaries right out of the box:

• Countries
• Currencies
• Timezones

Building your own dictionary

It's really easy to build your own dictionary...

1. Generate a dictionary class using php please:

    php please make:dictionary Provinces

   If you want to generate a dictionary for an addon, use the --addon parameter.

2. In your app/Dictionaries directory (or src/Dictionaries in an addon), you'll see your new Provinces dictionary has been generated:

   class Provinces extends Dictionary
   /** * Returns a key/value array of options. * * @param string|null $search * @return array */
   public functionoptions(?string$search = null): array
   {
   return$this->getItems()
   ->when($search ?? false, function ($collection) use ($search) {
   return$collection->filter(fn ($item) => str_contains($item['name'], $search));
   })
   ->mapWithKeys(fn ($item) => [$item['slug'] => $item['name']])
   ->all();
   }
   /** * Returns a single option. * * @param string $key * @return string|array */publicfunctionget(string$key): string|array
   {
   return$this->getItems()->firstWhere('slug', $key);
   }
   privatefunctiongetItems(): Collection
   {
   returncollect([
   ['name' => 'January', 'slug' => 'january'],
   ['name' => 'February', 'slug' => 'february'],
   ['name' => 'March', 'slug' => 'march'],
   // ...
   ]);
   } }

   • The options method should return a key/value array of all options.
     • The $search variable will be provided if the user is searching options. Feel free to search the options in whatever way works for you.
   • The get method should return a single option.
     • This will be made available when the dictionary field's options are augmented. You're free to return whatever you need here.
   • Optionally, you can also configure "config fields" for the dictionary which will be available in the dictionary's context:

   protectedfunctionfieldItems()
   {
   return [
   'region' => [
   'display' => __('Region'),
   'instructions' => __('statamic::messages.dictionaries_countries_region_instructions'),
   'type' => 'select',
   'options' => $this->getCountries()->unique('region')->pluck('region', 'region')->filter()->all(),
   ],
   ];
   }
   publicfunctionget(string$key): string|array
   {
   $region = $this->context['region'];
   // ...
   }

[jasonvarga]

I've made a whole bunch of tweaks. The initial description of this PR is fairly outdated now. The docs PR is the most up to date source now. statamic/docs#1405

tl;dr:

• Added an opinionated BasicDictionary subclass that devs can extend, making custom dictionaries way simpler. Basically just need to define an array of items.
• Added a File dictionary, letting users grab a JSON or YAML file from somewhere, throw into their app, and then they can have a custom dictionary without writing any PHP. (It should be trivial to support other file types later like xml, csv, etc)

[duncanmcclean]

This pull request introduces the concept of Dictionaries to Statamic.

The Dictionary fieldtype works in a similar way to the Select fieldtype. However, the main difference is that the options are returned from a PHP class (called a "dictionary"), instead of being defined in the field's config.

There's a few common use cases where this is helpful:

• When you have a YAML or JSON file with options, but you don't want to enter the options into a Select field manually.
• When the options are coming from an external API of some kind. Previously, you'd need to build your own relationship fieldtype for this.
• Probably others that I haven't thought of yet...

Available Dictionaries

Statamic includes a few helpful dictionaries right out of the box:

• Countries
• Currencies
• Timezones

Building your own dictionary

It's really easy to build your own dictionary...

1. Generate a dictionary class using php please:

    php please make:dictionary Provinces

   If you want to generate a dictionary for an addon, use the --addon parameter.

2. In your app/Dictionaries directory (or src/Dictionaries in an addon), you'll see your new Provinces dictionary has been generated:

   class Provinces extends Dictionary
   /** * Returns a key/value array of options. * * @param string|null $search * @return array */
   public functionoptions(?string$search = null): array
   {
   return$this->getItems()
   ->when($search ?? false, function ($collection) use ($search) {
   return$collection->filter(fn ($item) => str_contains($item['name'], $search));
   })
   ->mapWithKeys(fn ($item) => [$item['slug'] => $item['name']])
   ->all();
   }
   /** * Returns a single option. * * @param string $key * @return string|array */publicfunctionget(string$key): string|array
   {
   return$this->getItems()->firstWhere('slug', $key);
   }
   privatefunctiongetItems(): Collection
   {
   returncollect([
   ['name' => 'January', 'slug' => 'january'],
   ['name' => 'February', 'slug' => 'february'],
   ['name' => 'March', 'slug' => 'march'],
   // ...
   ]);
   } }

   • The options method should return a key/value array of all options.
     • The $search variable will be provided if the user is searching options. Feel free to search the options in whatever way works for you.
   • The get method should return a single option.
     • This will be made available when the dictionary field's options are augmented. You're free to return whatever you need here.
   • Optionally, you can also configure "config fields" for the dictionary which will be available in the dictionary's context:

   protectedfunctionfieldItems()
   {
   return [
   'region' => [
   'display' => __('Region'),
   'instructions' => __('statamic::messages.dictionaries_countries_region_instructions'),
   'type' => 'select',
   'options' => $this->getCountries()->unique('region')->pluck('region', 'region')->filter()->all(),
   ],
   ];
   }
   publicfunctionget(string$key): string|array
   {
   $region = $this->context['region'];
   // ...
   }

[jasonvarga]

I've made a whole bunch of tweaks. The initial description of this PR is fairly outdated now. The docs PR is the most up to date source now. statamic/docs#1405

tl;dr:

• Added an opinionated BasicDictionary subclass that devs can extend, making custom dictionaries way simpler. Basically just need to define an array of items.
• Added a File dictionary, letting users grab a JSON or YAML file from somewhere, throw into their app, and then they can have a custom dictionary without writing any PHP. (It should be trivial to support other file types later like xml, csv, etc)

[duncanmcclean]

This pull request introduces the concept of Dictionaries to Statamic.

The Dictionary fieldtype works in a similar way to the Select fieldtype. However, the main difference is that the options are returned from a PHP class (called a "dictionary"), instead of being defined in the field's config.

There's a few common use cases where this is helpful:

• When you have a YAML or JSON file with options, but you don't want to enter the options into a Select field manually.
• When the options are coming from an external API of some kind. Previously, you'd need to build your own relationship fieldtype for this.
• Probably others that I haven't thought of yet...

Available Dictionaries

Statamic includes a few helpful dictionaries right out of the box:

• Countries
• Currencies
• Timezones

Building your own dictionary

It's really easy to build your own dictionary...

1. Generate a dictionary class using php please:

    php please make:dictionary Provinces

   If you want to generate a dictionary for an addon, use the --addon parameter.

2. In your app/Dictionaries directory (or src/Dictionaries in an addon), you'll see your new Provinces dictionary has been generated:

   class Provinces extends Dictionary
   /** * Returns a key/value array of options. * * @param string|null $search * @return array */
   public functionoptions(?string$search = null): array
   {
   return$this->getItems()
   ->when($search ?? false, function ($collection) use ($search) {
   return$collection->filter(fn ($item) => str_contains($item['name'], $search));
   })
   ->mapWithKeys(fn ($item) => [$item['slug'] => $item['name']])
   ->all();
   }
   /** * Returns a single option. * * @param string $key * @return string|array */publicfunctionget(string$key): string|array
   {
   return$this->getItems()->firstWhere('slug', $key);
   }
   privatefunctiongetItems(): Collection
   {
   returncollect([
   ['name' => 'January', 'slug' => 'january'],
   ['name' => 'February', 'slug' => 'february'],
   ['name' => 'March', 'slug' => 'march'],
   // ...
   ]);
   } }

   • The options method should return a key/value array of all options.
     • The $search variable will be provided if the user is searching options. Feel free to search the options in whatever way works for you.
   • The get method should return a single option.
     • This will be made available when the dictionary field's options are augmented. You're free to return whatever you need here.
   • Optionally, you can also configure "config fields" for the dictionary which will be available in the dictionary's context:

   protectedfunctionfieldItems()
   {
   return [
   'region' => [
   'display' => __('Region'),
   'instructions' => __('statamic::messages.dictionaries_countries_region_instructions'),
   'type' => 'select',
   'options' => $this->getCountries()->unique('region')->pluck('region', 'region')->filter()->all(),
   ],
   ];
   }
   publicfunctionget(string$key): string|array
   {
   $region = $this->context['region'];
   // ...
   }

[jasonvarga]

I've made a whole bunch of tweaks. The initial description of this PR is fairly outdated now. The docs PR is the most up to date source now. statamic/docs#1405

tl;dr:

• Added an opinionated BasicDictionary subclass that devs can extend, making custom dictionaries way simpler. Basically just need to define an array of items.
• Added a File dictionary, letting users grab a JSON or YAML file from somewhere, throw into their app, and then they can have a custom dictionary without writing any PHP. (It should be trivial to support other file types later like xml, csv, etc)