📦 Squehub Packages

Packages in Squehub are modular components adding features such as APIs, utilities, or datasets. Each package follows a standardized directory structure with a required main entry PHP file named exactly after the package (e.g., Weather.php for the weather package) which bootstraps and exposes package functionality. Packages are typically developed on GitHub and installed locally.

🛠 Naming Conventions for Package Developers

To avoid naming conflicts in the Squehub ecosystem, developers should use clear, unique package names that combine their brand or developer name with the package purpose. For example, if your brand is Sky and you are building an authentication package, use a combined name like:

• skyauth (no spaces, lowercase)

The package namespace should mirror this naming for consistency, for example:

• Package name: skyauth
• Namespace: Packages\Skyauth

This helps avoid collisions, simplifies autoloading, and keeps your packages organized within the Squehub ecosystem.

📁 Recommended Directory Structure

Each package must reside under project/packages/ and include the following essential components:

• Main entry file: A PHP file named exactly after the package (case-sensitive), e.g., Weather.php. This file serves as the bootstrap and public API of your package, initializing internal services and exposing package features.
• Subdirectories: Organize your package code into meaningful folders representing MVC structure, utilities, configuration, and routes.

project/
└── packages/
    └── weather/
        ├── Weather.php         <-- Main entry file (bootstrap & API)
        ├── Controllers/        <-- HTTP controllers, e.g., WeatherController.php
        ├── Models/             <-- Data models, e.g., Weather.php
        ├── Middleware/         <-- Middleware classes, e.g., AuthMiddleware.php
        ├── Utils/              <-- Helper functions, e.g., helpers.php
        ├── Views/              <-- Blade-like templates
        │   ├── layouts/        <-- Layout templates, e.g., main-layout.squehub.php
        │   └── pages/          <-- Page templates, e.g., forecast.squehub.php
        ├── Routes/             <-- Route files, e.g., web.php, api.php
        ├── config/             <-- Configuration files, e.g., config.php
        └── composer.json       <-- Package metadata and autoloading config

Directory Details and Example Files

• Weather.php: The package’s main PHP file responsible for bootstrapping and exposing public API methods.
• Controllers/: Contains classes handling HTTP requests. Example: WeatherController.php with methods like index() or showForecast(). Follow Squehub Controllers Standard.
• Models/: Data models representing entities or database tables. Example: Weather.php model with methods to fetch weather data. Follow Squehub Models Standard.
• Middleware/: Classes for request filtering or authentication. Example: AuthMiddleware.php protecting routes. Follow Squehub Middleware Standard.
• Utils/: Helper PHP files containing reusable functions or classes. Example: helpers.php with date or formatting utilities.
• Views/: Blade-like templating files for UI rendering.
  • layouts/: Layout templates like main-layout.squehub.php for common page structure.
  • pages/: Specific page templates like forecast.squehub.php.
  Follow Squehub Views Standard.
• Routes/: Route definition files registering package-specific routes. Examples: web.php for frontend, api.php for API endpoints. Follow Squehub Routes Standard.
• config/: Configuration files defining package options. Example: config.php with settings for API keys or toggles.
• composer.json: Composer manifest declaring package name, namespace, dependencies, and autoloading rules.

Important: When building your package, use the official Squehub standards and conventions for Controllers, Models, Middleware, Views, and Routes. This ensures maximum compatibility and maintainability within Squehub apps.

⚙️ Core CLI Commands for Package Management

Squehub provides built-in CLI commands to simplify package installation and removal:

Install Package

Install a package from a GitHub repository into project/packages/:

php squehub package:install https://github.com/vendor/package-name

Remove Package

Remove an installed package by name:

php squehub package:remove package-name

How It Works

• package:install clones the GitHub repo into project/packages/package-name and refreshes Composer autoload.
• package:remove recursively deletes the package directory and refreshes Composer autoload.

📂 Manual Import

Alternatively, you can manually import packages by downloading and placing them directly into the project/packages/ directory. Follow these steps:

1. Download the package archive (usually a ZIP file) from the package’s GitHub repository or other source.
2. Extract/Unzip the downloaded archive to a temporary folder on your local machine.
3. Move or copy the extracted package folder into your Squehub project’s project/packages/ directory. Ensure the folder name matches the package name, and the package contains the required structure including the main entry PHP file.
4. Refresh Composer autoload from your project root to register the new package's namespace and classes:

   composer dump-autoload

5. After this, you can start using the package classes, routes, views, and other resources within your application.

Note: Make sure the package follows Squehub’s naming conventions and directory structure to ensure smooth integration.

📦 Main Entry Class

Each package’s main entry class (e.g., Packages\Weather\Weather) acts as the API and bootstrap for the package.

use Packages\Weather\Weather;

$forecast = Weather::today();

🧩 Example composer.json Inside a Package

Example package manifest:

{
  "name": "squehub/weather",
  "description": "Provides weather forecast utilities.",
  "type": "squehub-package",
  "license": "MIT",
  "authors": [
    {
      "name": "Jane Developer",
      "email": "jane@example.com"
    }
  ],
  "autoload": {
    "psr-4": {
      "Packages\\Weather\\": "./"
    }
  },
  "require": {}
}

📘 Package vs Kit

• Packages are modular units that often focus on specific features like APIs, utilities, or services. While traditionally more logic-focused, packages in Squehub can also include routes, views, controllers, middleware, and configuration as needed, making them fully capable of providing reusable application components.
• Kits are more comprehensive scaffolds that bundle multiple packages and provide a full solution including extensive routes, views, controllers, and often prebuilt UI. Examples include auth, blog-kit, and similar feature-rich starters.