PHP Namespaces Explained — Avoid Conflicts, Organize Code Like a Pro

<?php
// FILE 1: vendor/slacknotify/src/Logger.php
namespace SlackNotify\Logging;  // This file lives in the SlackNotify\Logging namespace

class Logger
{
    public function log(string $message): void
    {
        // Pretend this sends a Slack message
        echo "[SlackNotify] " . $message . PHP_EOL;
    }
}


// FILE 2: vendor/monolog/src/Logger.php
namespace Monolog;  // This file lives in the Monolog namespace

class Logger
{
    public function log(string $message): void
    {
        // Pretend this writes to a log file
        echo "[Monolog] " . $message . PHP_EOL;
    }
}


// FILE 3: index.php  — Using BOTH classes with zero conflict
require 'vendor/slacknotify/src/Logger.php';
require 'vendor/monolog/src/Logger.php';

// 'use' imports the fully-qualified name so we can write short aliases
use SlackNotify\Logging\Logger as SlackLogger;  // alias to avoid ambiguity
use Monolog\Logger as MonologLogger;             // alias to avoid ambiguity

$slackLogger   = new SlackLogger();    // creates SlackNotify\Logging\Logger
$monologLogger = new MonologLogger();  // creates Monolog\Logger

$slackLogger->log('User signed up');    // routes to SlackNotify version
$monologLogger->log('User signed up');  // routes to Monolog version

<?php
declare(strict_types=1);  // declare() is the ONE thing allowed before namespace

namespace App\Services\Payments;  // mirrors the directory: src/Services/Payments/

// No imports needed yet — everything in THIS namespace is available by default

class PaymentGateway
{
    private string $providerName;
    private float  $transactionFee;

    public function __construct(string $providerName, float $transactionFee)
    {
        $this->providerName   = $providerName;
        $this->transactionFee = $transactionFee;
    }

    public function charge(float $amount): string
    {
        // Calculate total including the gateway's processing fee
        $totalCharged = $amount + $this->transactionFee;

        return sprintf(
            'Charged $%.2f via %s (includes $%.2f fee)',
            $totalCharged,
            $this->providerName,
            $this->transactionFee
        );
    }
}


// ── index.php ─────────────────────────────────────────────────────────────────
// In a real project Composer autoloads this. Here we require manually.
require 'PaymentGateway.php';

use App\Services\Payments\PaymentGateway;  // import the fully-qualified name

$stripeGateway = new PaymentGateway('Stripe', 0.30);  // $0.30 flat fee
$paypalGateway = new PaymentGateway('PayPal', 0.49);  // $0.49 flat fee

echo $stripeGateway->charge(19.99) . PHP_EOL;
echo $paypalGateway->charge(19.99) . PHP_EOL;

<?php
declare(strict_types=1);

namespace App\Http\Controllers;

// Import a third-party class with a long namespace — alias it for brevity
use App\Services\Payments\PaymentGateway;
use App\Services\Payments\PaymentGateway as Gateway;  // alias: type 'Gateway' instead

// Import global PHP classes explicitly — don't rely on implicit fallback
use DateTime;      // tells PHP: DateTime means \DateTime, the global built-in
use RuntimeException;  // same for exceptions

class OrderProcessor
{
    private Gateway $paymentGateway;  // using the alias 'Gateway' — cleaner!

    public function __construct(Gateway $paymentGateway)
    {
        $this->paymentGateway = $paymentGateway;
    }

    public function processOrder(string $orderId, float $total): array
    {
        if ($total <= 0) {
            // 'RuntimeException' resolves to global \RuntimeException because of our 'use' above
            throw new RuntimeException("Order {$orderId} has an invalid total: {$total}");
        }

        $chargeResult = $this->paymentGateway->charge($total);

        // 'DateTime' resolves to global \DateTime because of our 'use' above
        $processedAt = new DateTime();

        return [
            'order_id'     => $orderId,
            'result'       => $chargeResult,
            'processed_at' => $processedAt->format('Y-m-d H:i:s'),
        ];
    }
}


// ── run_order.php ─────────────────────────────────────────────────────────────
require 'PaymentGateway.php';
require 'OrderProcessor.php';

use App\Http\Controllers\OrderProcessor;
use App\Services\Payments\PaymentGateway;

$gateway   = new PaymentGateway('Stripe', 0.30);
$processor = new OrderProcessor($gateway);

$result = $processor->processOrder('ORD-7821', 49.99);

foreach ($result as $key => $value) {
    echo $key . ': ' . $value . PHP_EOL;
}

<?php
/**
 * SIMULATED DIRECTORY STRUCTURE (in a real project, Composer handles the requires):
 *
 * src/
 *   Models/Product.php          -> namespace App\Models
 *   Repositories/ProductRepo.php -> namespace App\Repositories
 *   Controllers/ShopController.php -> namespace App\Controllers
 * index.php
 *
 * composer.json autoload section:
 * "autoload": { "psr-4": { "App\\": "src/" } }
 */

// ── src/Models/Product.php ────────────────────────────────────────────────────
namespace App\Models;

class Product
{
    public function __construct(
        public readonly int    $id,
        public readonly string $name,
        public readonly float  $price,
        public readonly int    $stockQuantity
    ) {}

    public function isInStock(): bool
    {
        return $this->stockQuantity > 0;  // simple stock check
    }

    public function getFormattedPrice(): string
    {
        return '$' . number_format($this->price, 2);  // format to 2 decimal places
    }
}


// ── src/Repositories/ProductRepository.php ───────────────────────────────────
namespace App\Repositories;

use App\Models\Product;  // import Product from the Models namespace

class ProductRepository
{
    /** @var Product[] */
    private array $products = [];

    public function __construct()
    {
        // Seed with demo data — in production this would query a database
        $this->products = [
            new Product(1, 'Mechanical Keyboard', 129.99, 14),
            new Product(2, 'USB-C Hub',            39.99,  0),  // out of stock
            new Product(3, 'Monitor Stand',         59.99,  7),
        ];
    }

    /** @return Product[] */
    public function findAllInStock(): array
    {
        // Filter to only products with stock > 0
        return array_filter($this->products, fn(Product $p) => $p->isInStock());
    }

    public function findById(int $productId): ?Product
    {
        foreach ($this->products as $product) {
            if ($product->id === $productId) {
                return $product;  // found it — return immediately
            }
        }
        return null;  // not found — return null, let the caller decide what to do
    }
}


// ── src/Controllers/ShopController.php ───────────────────────────────────────
namespace App\Controllers;

use App\Repositories\ProductRepository;  // import the repository
use RuntimeException;                    // global PHP exception — explicit import

class ShopController
{
    private ProductRepository $productRepository;

    public function __construct(ProductRepository $productRepository)
    {
        // Dependency injected — no 'new ProductRepository()' buried in here
        $this->productRepository = $productRepository;
    }

    public function listInStockProducts(): void
    {
        $inStockProducts = $this->productRepository->findAllInStock();

        echo "=== In-Stock Products ==" . PHP_EOL;
        foreach ($inStockProducts as $product) {
            echo sprintf(
                "  [%d] %-22s %s (%d in stock)%s",
                $product->id,
                $product->name,
                $product->getFormattedPrice(),
                $product->stockQuantity,
                PHP_EOL
            );
        }
    }

    public function showProduct(int $productId): void
    {
        $product = $this->productRepository->findById($productId);

        if ($product === null) {
            throw new RuntimeException("Product ID {$productId} not found.");
        }

        $stockStatus = $product->isInStock() ? 'In Stock' : 'OUT OF STOCK';

        echo PHP_EOL . "=== Product Detail ==" . PHP_EOL;
        echo "Name:   {$product->name}" . PHP_EOL;
        echo "Price:  {$product->getFormattedPrice()}" . PHP_EOL;
        echo "Status: {$stockStatus}" . PHP_EOL;
    }
}


// ── index.php (entry point) ───────────────────────────────────────────────────
// In a real project: require 'vendor/autoload.php'; — that's the only require needed
use App\Repositories\ProductRepository;
use App\Controllers\ShopController;

$repository = new ProductRepository();
$controller = new ShopController($repository);  // inject the dependency

$controller->listInStockProducts();  // list everything in stock
$controller->showProduct(2);         // show USB-C Hub — which is out of stock