🚀 Intro

Official eWeLink API documentation

Possible API endpoints for the standard role:

📚 Project statement

• MIT license (use it however you like, but keep attribution)
• The main branch is intended to be operational
• Set DEBUG = 1 in Constants.php to log every API request (with parameters and output) to debug.log

🧭 Project structure

ewelinkApiPhp/
├── .github/
│   └── workflows/
│       └── ci.yml            # GitHub Actions matrix CI: PHP 7.4–8.5, Composer install, tests & QA checks
├── src/
│   ├── Config.php            # Loads & merges config (Constants ⇢ optional JSON_LOG_DIR/config.json ⇢ runtime overrides)
│   ├── Constants.php         # Defaults & switches (APP IDs, secrets, SAVE_CONFIG_JSON, JSON_LOG_DIR, DEBUG, error codes)
│   ├── HttpClient.php        # Signs requests; helpers/factories (Token, Devices, Home)
│   ├── Token.php             # OAuth flow: get/refresh/validate tokens; persists to token.json; security redirects
│   ├── Utils.php             # Helpers: nonce/signature, config & JSON validation, debug logger, security warnings
│   ├── Home.php              # Thin façade over /v2/family endpoints; caches family/room lists; exposes current family ID
│   └── Devices.php           # High-level device API: discovery, live status, multi-channel helpers, search & control
├── tests/
│   ├── ConstantsTest.php     # PHPUnit smoke tests for constant values (autoload-dev excluded from classmap)
│   └── config/
│       ├── phpunit.xml.dist  # PHPUnit bootstrap, coverage & colors settings (run via `composer test`)
│       └── phpstan.neon.dist # PHPStan rules for static analysis (run via `composer stan`)
├── gateway.php               # Demo gateway: composer autoload → OAuth login → list devices in the browser
├── README.md
├── composer.json             # Package metadata, PSR-4 map, QA scripts (`test`, `stan`, `cs`, `cs-fix`)
├── LICENSE (MIT)             # MIT license text – do what you want, keep attribution
├── .gitignore                # Ignores vendor/, debug.log, *.json, IDE files, etc.
└── .gitattributes            # Normalizes line endings & export settings for archives

All classes are located in the src directory.

[!TIP] By default, JSON outputs (including config.json, token.json, devices.json, and debug.log) are saved in the project root.
You can change the storage directory via JSON_LOG_DIR in Constants.php or at runtime with overrides.

⚙️ Configuration options

Configuration can be provided at three levels. Precedence is:

runtime overrides ➜ config.json (when enabled) ➜ Constants.php

1. Constants.php (defaults & switches)
   Define your baseline values:

   • APPID, APP_SECRET, REDIRECT_URL, EMAIL, PASSWORD, REGION
   • DEBUG (0/1) – enables verbose logging to debug.log
   • JSON_LOG_DIR – where all JSON/log files live (default: project root)
   • SAVE_CONFIG_JSON (true/false)
     • true (default): read & write JSON_LOG_DIR/config.json
     • false: ignore config.json entirely and never write it
       If a stale config.json exists, the library will display a notice recommending deletion.

2. config.json (optional)
   Used only when SAVE_CONFIG_JSON === true.
   After the first OAuth, the effective configuration is written to config.json. On subsequent runs it is merged on top of Constants.php.
   Path: JSON_LOG_DIR/config.json.

3. Runtime overrides (best for multi-site / multi-user)
   Pass an associative array to new HttpClient($overrides) (or call Config::setOverrides([...]) before use).
   Overrides are merged last, so they win over both config.json and Constants.php.
   Typical use: set a per-site JSON_LOG_DIR, different credentials, region, or debug level without touching files.

✅ Supported runtime override keys

You can override any of the following at runtime:

• APPID
• APP_SECRET
• REDIRECT_URL
• EMAIL
• PASSWORD
• REGION (cn, us, eu, as)
• DEBUG (0/1)
• JSON_LOG_DIR (controls where config.json, token.json, debug.log, etc. are stored)

Note: SAVE_CONFIG_JSON is a project-level constant (read at runtime) and not designed to be overridden at runtime. Set it in Constants.php.

🧩 Example (gateway.php)

<?php
use pjanisio\ewelinkapiphp\HttpClient;

/**
 * A) Default (backward compatible)
 *    - Constants + (if enabled) JSON_LOG_DIR/config.json
 *    - SAVE_CONFIG_JSON=true (default) → read/write config.json
 */
$http = new HttpClient();

/**
 * B) Disable config.json completely
 *    - Set SAVE_CONFIG_JSON=false in Constants.php
 *    - Library ignores config.json even if present and will not write it
 */
$http = new HttpClient();

/**
 * C) Per-run overrides (win over both constants and config.json)
 *    - Great for multi-site isolation (custom JSON_LOG_DIR, creds, region)
 */
$overrides = [
    'APPID'        => 'your_app_id',
    'APP_SECRET'   => 'your_app_secret',
    'REDIRECT_URL' => 'https://yourdomain.com/ewelinkApiPhp/gateway.php',
    'EMAIL'        => '[email protected]',
    'PASSWORD'     => 'your_password',
    'REGION'       => 'eu',
    'JSON_LOG_DIR' => __DIR__ . '/json_logs', // must be writable
    'DEBUG'        => 0,
];
$http = new HttpClient($overrides);

[!NOTE] If SAVE_CONFIG_JSON=false and JSON_LOG_DIR/config.json still exists, a notice will be shown suggesting that you delete the file to fully disable file-based config.
A security warning is also shown if config.json resides under your web root.

🤝 Contribution guidelines

Thank you for your interest in contributing! Please follow these steps:

1) Fork the repository

• Click Fork at the top-right of this page to create your copy of the repo.

2) Work on the code

• Clone your fork locally.
• Implement your changes and test with Composer.

Use Composer scripts to check code:

composer install   # install dependencies (skip if already installed)
composer cs        # run code sniffer (warnings allowed)
composer cs-fix    # auto-fix style issues (phpcbf)

3) Create a pull request

• Add clear labels
• Request a reviewer

🧪 CI tests

Currently we test:

• eWeLink API gateways
• Compatibility across PHP versions
• Composer installation, code style, and PHPStan (level 3)

Before drafting a PR or committing to the repo, run:

composer install
composer cs
composer cs-fix

All tests are managed by .github/workflows/ci.yml.

🧾 Versioning

We follow Semantic Versioning.