Laravel 10: Чтение JSON файлов

Введение

Могут быть случаи, когда вы создаёте Laravel приложение и нужно прочитать файл JSON.

Мне часто приходится это делать, во время написания тестов для интеграции API и я хочу прочитать фиктивный ответ, ранее сохранённый в файле JSON. Мне также приходилось делать это, когда я работал со сторонними службами (такими как Firebase), предоставляющими JSON файл для передачи в SDK для аутентификации.

В этой статье мы кратко рассмотрим, как использовать новый метод File::json добавленный в Laravel 10.4 Austin White в PR #46481. Также рассмотрим, как использовать аналогичный метод Storage::json, добавленный в Laravel 10.5 lorenzolosa в PR #46548

Затем мы быстро сравним различия между этими двумя методами и способы улучшения обработки ошибок.

Чтение JSON файла с использованием Фасада File

Метод File::json — это простая обёртка вокруг функции json_decode и метода File::get. Она позволяет читать JSON файл из локальной файловой системы и возвращать содержимое в виде массива.

Раньше, если вы хотели прочитать JSON файл в Laravel приложении, вы могли написать что-то вроде этого:

$contents = File::get(base_path('path/to/file.json'));
$json = json_decode($contents);

Предполагая, что JSON файл валиден, переменная $json теперь будет массивом, содержащим содержимое JSON файла.

Например, предположим, что JSON файл содержит следующие данные:

{
    "name": "laravel/laravel",
    "type": "project",
    "description": "The Laravel Framework.",
    "keywords": [
        "framework",
        "laravel"
    ]
}

Переменная $json будет содержать следующие данные массива:

[
    'name' => 'laravel/laravel',
    'type' => 'project',
    'description' => 'The Laravel Framework.',
    'keywords' => [
        'framework',
        'laravel',
    ],
]

Мы можем добиться точно такого же поведения, используя новый метод File::json следующим образом:

$json = File::json(base_path('path/to/file.json'));

Хотя это небольшое изменение, мне оно очень нравится!

Я большой фанат того, чтобы мой код читался как можно ближе к простому английскому языку, и я чувствую, что этот метод помогает в этом. Всякий раз, когда я пишу какой-либо код, я пытаюсь подумать про себя: Сможет ли джуниор, присоединившийся к команде, понять, что происходит?.

Конечно, это одно маленькое изменение не сделает, волшебным образом, ваш код читаемым для всех, но я думаю, что такие небольшие изменения, со временем принесут пользу.

Чтение JSON файла с использованием Фасада Storage

Как и метод File::json, в laravel также есть метод Storage::json, который можно использовать для чтения JSON файлов.

В то время как File::json используется для чтения JSON файлов из локальной файловой системы, метод Storage::json используется для чтения JSON файлов с диска хранилища вашего приложения. Это означает, что вы можете использовать Storage::json для чтения файлов из AWS S3 bucket, Digital Ocean Spaces, и т.д.

Вы можете вызывать этот метод точно так же, как и метод File::json:

$json = Storage::json('path/to/file.json');

Обработка ошибок

Различное поведение для несуществующих файлов

На момент написания этой статьи важно отметить, что File::json и Storage::json ведут себя немного по-разному, когда дело доходит до работы с несуществующими файлами.

Когда вы пытаетесь прочитать несуществующий файл с помощью метода File::json, он вызовет исключение Illuminate\Contracts\Filesystem\FileNotFoundException. Однако если вы попытаетесь прочитать несуществующий файл с помощью метода Storage::json, он вернёт значение null.

Это то, что вам нужно помнить при использовании этих методов и выборе наилучшего подхода к обработке ошибок.

Чтение недопустимых JSON файлов

Вы всегда должны помнить о валидации содержимого JSON файла, прежде чем пытаться его использовать.

Допустим, у вас есть следующий недопустимый JSON файл (с пропущенной запятой в конце предпоследней строки, вызывающей ошибку):

{
    "name": "laravel/laravel",
    "type": "project",
    "description": "The Laravel Framework.",
    "keywords": [
        "framework",
        "laravel"
    ],
}

Если вы попытаетесь использовать метод Storage::json или File::json для чтения этого файла, оба метода вернут значение null. Это происходит потому, что функция json_decode возвращает значение null, если не может декодировать JSON строку.

Это связано с тем, что базовый метод json_decode использует 0 (JSON_ERROR_NONE) в качестве флага по умолчанию. Это означает, что он не будет выбрасывать исключение, если обнаружит ошибку.

Как правило, я предпочитаю, чтобы в случае ошибки выбрасывалось исключение, которое я был бы вынужден обработать. Это гарантирует, что я не буду использовать неверные данные в приложении, и может предупредить меня в баг-трекере, что бы я мог исправить ошибку. Для этого вы можете передать флаг JSON_THROW_ON_ERROR методам следующим образом:

$json = Storage::json('path/to/file.json', JSON_THROW_ON_ERROR);

$json = File::json('path/to/file.json', JSON_THROW_ON_ERROR);

Теперь, если какой-нибудь из этих методов не сможет декодировать JSON строку, будет выброшено исключение JsonException.

Заключение

Надеюсь эта статья дала вам представление о том, как вы можете использовать новые методы File::json и Storage::json для чтения JSON файлов в Laravel.