LETUNOFF DOCS

PHP. Пространства имён (namespace) и PSR-4

🧱 Суть

Namespace (пространство имён) – механизм PHP для группировки классов, функций и констант и предотвращения конфликтов имён.

Пример:

namespace App\Models;
 
class User
{
}

Теперь класс имеет полное имя:

App\Models\User

📦 Проблема

1. Конфликт имён классов

В больших проектах могут существовать классы с одинаковыми названиями:

class User {}

Например:

App\Models\User
App\Admin\User

Без namespace PHP не сможет понять, какой класс использовать.

2. Большой проект сложно организовать

Без пространства имён все классы находятся в одной глобальной области:

User
Product
Order
Database
Logger

Со временем возникает путаница.

3. Ручное подключение файлов

Даже с разбиением на папки нужно писать:

require 'Models/User.php';
require 'Services/UserService.php';

Для этого используется автозагрузка PSR-4.

✅ Решение

Использовать:

  • namespace – для организации кода
  • use – для импорта классов
  • Composer Autoload + PSR-4 – для автоматического поиска файлов

💻 Код

Создание Namespace

Namespace указывается в начале файла:

<?php
 
namespace App\Models;
 
class User
{
}

Важно:

namespace

должен находиться после <?php и до любого другого кода.

Использование класса из другого Namespace

Например:

src/Models/User.php
namespace App\Models;
 
class User
{
}

Использование:

$user = new App\Models\User();

Это полное имя класса (FQCN – Fully Qualified Class Name).

Ключевое слово use

Чтобы не писать полный путь:

$user = new App\Models\User();

используют:

use App\Models\User;
 
$user = new User();

use создаёт короткую ссылку на класс.

Несколько классов с одинаковым названием

Например:

use App\Models\User;
use App\Admin\User;

Возникнет конфликт.

Решение – псевдоним:

use App\Models\User as ModelUser;
use App\Admin\User as AdminUser;
 
 
$model = new ModelUser();
$admin = new AdminUser();

Глобальное пространство имён

Если namespace не указан:

class User
{
}

Класс находится в глобальном пространстве:

\User

Можно явно обратиться:

$user = new \User();

Обратный слэш \ означает корневое пространство имён.

Что такое PSR-4

PSR-4 – стандарт Composer для автоматической загрузки классов.

Он определяет правило:

Namespace класса должен соответствовать структуре папок и имени файла.

Пример PSR-4

Структура:

project/
│
├── src/
│   └── Models/
│       └── User.php
│
└── composer.json

Файл:

// src/Models/User.php
 
namespace App\Models;
 
class User
{
}

composer.json:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

После выполнения:

composer dump-autoload

Composer создаст карту соответствий:

App\ → src/

Теперь:

use App\Models\User;
 
$user = new User();

автоматически загрузит:

src/Models/User.php

Как работает PSR-4

Логика преобразования:

App\Models\User
        ↓
убираем App\
        ↓
Models\User
        ↓
заменяем \ на /
        ↓
Models/User.php
        ↓
src/Models/User.php

Типичная структура PHP-проекта

project/
│
├── src/
│   ├── Controllers/
│   │   └── UserController.php
│   │
│   ├── Models/
│   │   └── User.php
│   │
│   ├── Services/
│   │   └── UserService.php
│
├── public/
│   └── index.php
│
├── vendor/
│
└── composer.json

Namespace обычно повторяет структуру:

namespace App\Controllers;
 
class UserController
{
}

Автозагрузка через Composer

В начале приложения подключают:

require_once __DIR__ . '/vendor/autoload.php';

После этого классы загружаются автоматически:

use App\Services\UserService;
 
$service = new UserService();

Частые ошибки

Namespace не совпадает с папками

Плохо:

namespace App\Models;
 
class User {}

Файл:

src/User.php

PSR-4 не найдёт класс.

Забыли обновить autoload

После изменения структуры:

composer dump-autoload

Неправильное использование use

use не подключает файл напрямую:

use App\Models\User;

Он только создаёт ссылку на класс.

Загрузка происходит через Composer Autoload.

🎯 Вывод

  • Namespace помогает организовать код и избегать конфликтов имён
  • use позволяет использовать короткие имена классов
  • PSR-4 связывает namespace с файловой структурой
  • Composer автоматически загружает нужные классы
  • современные PHP-проекты почти всегда используют PSR-4 Autoload

🔗 Связано

Обратные ссылки