Doctrine array vs simple_array vs json_array

Doctrine array vs simple_array vs json_array

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Choosing Between Doctrine Array, SimpleArray, and JsonArray Types

When working with Symfony and Doctrine ORM, you often encounter a decision point regarding how to map complex data structures to database columns. You might see array, simple_array, or json_array available as column types. The distinction is not merely semantic; it dictates how Doctrine serializes data, what kind of queries are possible, and how your entity interacts with the underlying database schema.

The most critical choice lies between array and json_array. In modern Symfony projects running on PostgreSQL (version 9.5+) or MySQL (version 8.0+), you should almost exclusively use json_array. This type leverages native JSON storage capabilities, storing your data as a single blob in the database rather than serializing it into a string.

Using json_array offers significant advantages. Most importantly, it enables advanced querying directly on the nested data. With a simple scalar array (stored as a string), you cannot easily query specific values inside the array using Doctrine's QueryBuilder or DQL without complex regex workarounds. With a native JSON column, you can execute queries like "find all tasks where Monday is enabled" or "get tasks that contain both Wednesday and Friday."

The array type is essentially an alias for storing data as a serialized string (usually JSON text). It behaves similarly to json_array in terms of storage but lacks the native database-level optimizations and query capabilities. In many versions of Doctrine, choosing array simply results in the same string-based behavior as json_array, making json_array the preferred modern standard for explicit intent.

simple_array is a different beast entirely. This type forces Doctrine to treat the column as a scalar value representing an indexed array where keys are integers starting from 0. When you use simple_array, Doctrine will convert your PHP array into a string representation (often resembling 1,2,3 or a serialized list) before saving it. Crucially, this type does not support associative arrays (arrays with non-integer keys like 'monday' => true) when persisting to the database in older configurations, as it expects a specific scalar format. If your data structure relies on named keys for semantic meaning, simple_array is likely the wrong choice unless you are dealing with legacy systems that strictly require integer-indexed lists.

Handling Associative Arrays in Entities

Your example illustrates the most common pitfall: attempting to store an associative array of days (1 => true, 'monday' => false) using a type that expects a simple list.

If your goal is to enable or disable specific days of the week, simple_array will break this pattern because it cannot preserve the string keys ('monday', 'tuesday') or the boolean values in the way you expect when converting back from the database row. Doctrine will likely truncate your data or fail to hydrate the associative structure correctly.

For a TaskEntity with a $days attribute, json_array is the correct implementation. It allows you to maintain the full PHP array structure—including associative keys and boolean values—and query it efficiently.

Here is how you would configure this in your entity:

use Doctrine\DBAL\Types\JsonType;

class TaskEntity
{
    public function getDays()
    {
        return $this->days;
    }

    public function setDays($days)
    {
        $this->days = $days;
    }
}

And in your .orm.xml or annotation mapping (depending on your configuration):

<field name="days" type="json_array" />

Or, using the modern attribute syntax:

#[ORM\Column(type: 'json')]
private array $days;

Querying Your Data

With a json_array column, you can leverage Doctrine's JSON functions to filter tasks. For instance, to find all tasks where Sunday is enabled:

$qb = $repository->createQueryBuilder('t');
$qb->where('t.days[:0] = :monday') // Adjust index based on your key logic or use named keys if supported by DB driver
     ->setParameter('monday', true);

Note that querying JSON columns requires understanding the specific syntax supported by your database driver (PostgreSQL uses -> and ->> operators, while MySQL uses JSON_EXTRACT). Doctrine abstracts much of this, but you must ensure your query logic aligns with the native capabilities.

When to Use SimpleArray

You should only consider simple_array if you are working with legacy databases (like older versions of MySQL or SQLite where JSON types don't exist) and need to store a strictly indexed list of integers (e.g., [1, 2, 3]). If your application logic requires a flat list of items without named keys, simple_array ensures compatibility with older drivers that do not support native JSON blobs.

However, for modern stacks involving PostgreSQL or MySQL 8+, the trade-off is clear: stick with json_array to gain queryability and type safety, avoiding the fragility of string-based serialization found in array or simple_array.

Our network