🐘 Documentación Oficial de Phphone

Phphone es un framework y compilador híbrido PHP-Nativo de alto rendimiento para Android, iOS y Desktop. Empaca un runtime completo de PHP 8.4 embebido dentro de las aplicaciones móviles, permitiendo ejecutar controladores, bases de datos locales (SQLite3) y lógica de negocio directamente en el procesador del teléfono sin depender de servidores en la nube.

El Manifiesto Vanilla Mobile

Construye aplicaciones móviles nativas utilizando únicamente PHP 8.4, HTML5, CSS3 y JavaScript. Sin Flutter, sin React Native, sin Electron y sin dependencias pesadas.

Glosario de Términos

Phphone: El framework y compilador global que orquesta todo el proyecto.
Motor Kie (Kie Engine): El motor core en C++ que hospeda los binarios de PHP y el puente de comunicación JNI/Swift. Inyecta el objeto window.Kie en JavaScript.
Dual WebView: Arquitectura que superpone dos navegadores: uno frontal transparente para la interfaz local y uno trasero para cargar webs externas sin bloqueos de seguridad.
KieBridge: Canal de comunicación nativo entre JavaScript y el sistema operativo móvil.

Requisitos Previos

Dado que Phphone genera binarios nativos reales, necesitas las herramientas estándar de desarrollo instaladas en tu máquina:

PHP 8.0+ en tu terminal (para ejecutar el CLI orquestador).
Android Studio con Android SDK y un emulador configurado.
Xcode (Solo en macOS) con las Command Line Tools activas para compilar hacia iOS.

Instalación del CLI Global

Instala el CLI de Phphone con un solo comando en tu terminal:

En Windows (PowerShell Administrador):

PowerShell

irm https://phphone.xyz/install.ps1 | iex

En macOS / Linux:

Bash

curl -sS https://phphone.xyz/install.sh | bash

Opción Alternativa (Vía Composer / Packagist):

Si ya tienes Composer instalado en tu máquina, puedes generar un proyecto directamente desde el repositorio central oficial de Packagist:

Composer

composer create-project phphone/phphone mi-app

Flujo de Trabajo Paso a Paso

1. Crear un Proyecto Nuevo (Con CLI Oficial)

Terminal

phphone create "Mi Tienda" com.mitienda.app
cd mi-tienda

2. Probar con Hot Reload

Detecta automáticamente tu emulador o dispositivo conectado y recarga el código al guardar:

Terminal

phphone run

3. Personalizar Ícono y Pantalla de Carga (Splash)

Coloca tu icon.png y splash.png en la carpeta setup/ y ejecuta:

Terminal

phphone setup

4. Compilar para Producción (Release)

Genera el APK / AAB con cifrado AES-256 en RAM:

Terminal

phphone build apk --release

Ecosistema Frontend (TypeScript, Vite) & .phphoneignore

Phphone te da total libertad de stack. Puedes programar usando TypeScript, React/JSX, Vue, Tailwind CSS, Vite o paquetes de Composer. Para que estos entornos modernos convivan de forma óptima con la compilación móvil, el ciclo se divide en 3 pasos:

1. Flujo de Trabajo con Bundlers (Vite / TypeScript / Webpack)

Desarrollas y compilas tu frontend: Trabajas con tus fuentes TypeScript (.ts) o componentes y ejecutas tu comando de compilación (ej. npm run build o npx tsc) para que deposite el JavaScript (.js) y CSS resultante dentro de tu carpeta de assets (ej: src/js/app.js).
Configuras el archivo .phphoneignore: Excluyes del empaquetador móvil todas las carpetas y archivos pesados que solo sirven para desarrollo en PC (como node_modules/ o fuentes TS).
Ejecutas o compilas con Phphone: Corres phphone run o phphone build apk --release. El compilador ignorará la basura de desarrollo y empaquetará únicamente el JavaScript limpio y el backend PHP.

2. El Archivo `.phphoneignore` (Preconfigurado de Fábrica)

Cada proyecto creado con phphone create ya incluye un archivo .phphoneignore en su raíz listo para usar. Puedes editarlo para agregar o remover reglas de exclusión personalizadas según las herramientas que utilices:

.phphoneignore

# Dependencias y Bundlers de Frontend
node_modules/
package.json
package-lock.json
vite.config.js
tsconfig.json
src_ts/

# Dependencias pesadas o pruebas
tests/
.git/
.idea/
.vscode/
*.log

Resultado: Apps de Menos de 20 MB

Gracias a .phphoneignore, puedes usar las herramientas más modernas de JavaScript y CSS en tu máquina sin inflar el peso de la app móvil. Tu usuario final descarga un binario ultra-optimizado.

Navegador Nativo Oculto (Dual WebView)

Permite cargar pasarelas de pago o sitios externos sin problemas de CORS ni bloqueos de X-Frame-Options:

JavaScript (app.js)

// 1. Activar navegador de fondo
window.Kie.setBrowserActive(true);

// 2. Cargar la URL deseada
window.Kie.loadUrl('https://google.com');

// 3. Volver el fondo transparente en CSS
document.body.style.backgroundColor = 'transparent';

Manejo del Notch y Safe Areas (CSS)

Para evitar que el contenido quede oculto detrás de la cámara frontal o la barra de gestos:

CSS (style.css)

/* Header con padding adaptativo para el notch */
.header {
    padding-top: env(safe-area-inset-top, 20px);
}

/* Barra inferior adaptada a gestos */
.bottom-nav {
    padding-bottom: env(safe-area-inset-bottom, 20px);
}

/* Sensación táctil nativa */
body {
    -webkit-user-select: none;
    user-select: none;
    -webkit-tap-highlight-color: transparent;
    overscroll-behavior-y: none;
}

APIs Nativas de Hardware (Phphone\Device)

Accede directamente a los sensores y hardware del teléfono en PHP sin importar dependencias externas:

PHP (index.php)

use Phphone\Device;

// Tomar fotografía en Base64
$foto = Device::camera();

// Obtener coordenadas GPS
$gps = Device::gps(); // ['lat' => 4.6097, 'lng' => -74.0817]

// Autenticación Biométrica (Face ID / Huella)
if (Device::authenticate("Confirma tu identidad")) {
    Device::toast("Acceso Autorizado");
}

// Vibración Háptica
Device::vibrate(200);

// Llavero Seguro (Keychain / Keystore)
Device::secureWrite("token", "mi_secreto_123");
$token = Device::secureRead("token");

Método PHP	Descripción	Retorno
`Device::camera()`	Abre la cámara nativa y captura una foto.	`string (Base64)`
`Device::gps()`	Obtiene coordenadas precisas de geolocalización.	`array ['lat', 'lng']`
`Device::authenticate($msg)`	Solicita validación por Face ID o huella.	`bool`
`Device::vibrate($ms)`	Activa la respuesta háptica del motor de vibración.	`void`
`Device::toast($message)`	Muestra un mensaje flotante nativo en pantalla.	`void`
`Device::notification($title, $body)`	Despliega una notificación local inmediata.	`void`
`Device::getContacts()`	Recupera la lista de contactos del dispositivo.	`array`

Notificaciones Push (Firebase FCM)

Phphone incluye un motor unificado de notificaciones push. Controla el comportamiento desde el payload JSON de tu backend:

Parámetro	Tipo	Efecto Nativo
`tag` / `id`	string	Si se envía, reemplaza/actualiza la notificación previa (ideal para pedidos). Si se omite, se acumulan.
`group` / `thread_id`	string	Agrupa múltiples mensajes bajo una misma tarjeta (Estilo WhatsApp/Gmail).
`reply`	bool	Habilita el botón y campo de texto "Responder" en la propia notificación.

Base de Datos SQLite y Persistencia

Entorno de Solo-Lectura en APKs

En Android de producción, el directorio __DIR__ es de solo lectura. Para guardar datos persistentes en SQLite, usa siempre la ruta escribible nativa:

PHP Helper

function getDB() {
    $dataDir = __DIR__ . '/../../data';
    
    // Si estamos en APK de producción (Solo-Lectura)
    if (!is_writable(__DIR__)) {
        $temp = rtrim(sys_get_temp_dir(), '/\\');
        $dataDir = (strpos($temp, 'cache') !== false) 
            ? dirname($temp) . '/files/app_data' 
            : dirname($temp) . '/Documents/app_data';
    }
    
    if (!is_dir($dataDir)) @mkdir($dataDir, 0777, true);
    
    $pdo = new PDO('sqlite:' . $dataDir . '/database.sqlite');
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    return $pdo;
}

Tareas en Segundo Plano (Daemons)

Ejecuta tareas silenciosas de PHP en bucle usando servicios de primer plano nativos:

JavaScript (Disparador)

// Iniciar demonio que consulta cada 60 segundos
window.Kie.startDaemon(JSON.stringify({ 
    taskName: 'sync_data', 
    interval: 60 
}));

PHP (src/daemon.php)

<?php
$task = $_GET['task'] ?? 'unknown';
// Tu lógica periódica aquí (ej: sincronizar base de datos)

Buenas Prácticas & Prevención de Errores

Regla de Oro: Evitar Zend Bailouts

El motor PHP se mantiene vivo en memoria compartida. NUNCA uses exit; ni die();, ya que forzarán un cierre abrupto (crash) de la app móvil. Usa return o lanza excepciones dentro de bloques try/catch.

Limitación de Peticiones POST en Release

Debido a restricciones de seguridad del WebView de Android, las intercepciones de red destruyen el cuerpo de las peticiones POST. Para enviar datos de JS a PHP en local, envía tus datos codificados como JSON en peticiones GET:

fetch('api.php?data=' + encodeURIComponent(JSON.stringify(payload)))

🐘 Official Phphone Documentation

Phphone is a high-performance PHP-Native hybrid framework and compiler for Android, iOS, and Desktop. It packages a full embedded PHP 8.4 runtime inside mobile applications, allowing developers to execute controllers, local databases (SQLite3), and business logic directly on the phone processor without relying on cloud servers.

The Vanilla Mobile Manifesto

Build native mobile applications using solely PHP 8.4, HTML5, CSS3, and JavaScript. No Flutter, no React Native, no Electron, and zero bloated dependencies.

Glossary of Terms

Phphone: The overarching framework and compiler orchestrating the entire mobile ecosystem.
Kie Engine: The core C++ engine hosting precompiled PHP binaries and native JNI/Swift bridges. It injects the window.Kie object into the JavaScript runtime.
Dual WebView: Architecture layering two overlapping browsers: a front transparent browser for the local UI and a rear browser for external web content without security blocks.
KieBridge: Direct native communication channel between JavaScript and the mobile operating system.

Prerequisites

Since Phphone produces genuine native binaries, you need standard mobile development tools installed:

PHP 8.0+ in your terminal (to execute the CLI orchestrator).
Android Studio with Android SDK and a configured emulator/device.
Xcode (macOS only) with Command Line Tools enabled for iOS compilation.

Global CLI Installation

Install the Phphone CLI with a single command in your terminal:

On Windows (PowerShell Administrator):

PowerShell

irm https://phphone.xyz/install.ps1 | iex

On macOS / Linux:

Bash

curl -sS https://phphone.xyz/install.sh | bash

Alternative Setup (Via Composer / Packagist):

If you already have Composer globally installed on your system, initialize a new project directly from Packagist:

Composer

composer create-project phphone/phphone my-app

Step-by-Step Workflow

1. Create a New Project (Via Official CLI)

Terminal

phphone create "My Store" com.mystore.app
cd my-store

2. Test with Live Hot Reload

Automatically detects your connected emulator or physical device and refreshes upon saving:

Terminal

phphone run

3. Customize App Icon and Splash Screen

Place your icon.png and splash.png in the setup/ folder and run:

Terminal

phphone setup

4. Compile for Production (Release)

Generates encrypted APK / AAB with AES-256 RAM decryption:

Terminal

phphone build apk --release

Frontend Toolchains (TypeScript, Vite) & .phphoneignore

Phphone offers absolute stack freedom. You can build with TypeScript, React/JSX, Vue, Tailwind CSS, Vite, or Composer packages. The integration workflow is divided into 3 straightforward steps:

1. Modern Bundlers Workflow (Vite / TypeScript / Webpack)

Develop and build your frontend: Write TypeScript (.ts) or modular components and run your standard build step (e.g. npm run build or npx tsc) to emit ready .js and .css files into your project assets (e.g. src/js/app.js).
Exclude dev bloat with .phphoneignore: Exclude bulky development folders (like node_modules/ or raw TS source files) from the mobile packager.
Run or Package with Phphone: Execute phphone run or phphone build apk --release. The compiler strips development files and exclusively bundles clean JavaScript and the PHP runtime.

2. The `.phphoneignore` File (Preconfigured Out of the Box)

Every project created with phphone create comes with a preconfigured .phphoneignore file in the root directory:

.phphoneignore

# Frontend Dependencies & Bundlers
node_modules/
package.json
package-lock.json
vite.config.js
tsconfig.json
src_ts/

# Testing & Dev Environments
tests/
.git/
.idea/
.vscode/
*.log

Result: Apps Under 20 MB

Thanks to .phphoneignore, you can leverage cutting-edge JavaScript and CSS tooling on your machine without bloating your mobile binaries. End users download an ultra-lightweight app.

Background Native Browser (Dual WebView)

Allows loading external payment gateways or third-party web services without CORS or X-Frame-Options security restrictions:

JavaScript (app.js)

// 1. Activate background native browser
window.Kie.setBrowserActive(true);

// 2. Load target URL
window.Kie.loadUrl('https://google.com');

// 3. Make HTML body transparent
document.body.style.backgroundColor = 'transparent';

Notch & Safe Areas Handling (CSS)

Prevent UI elements from colliding with camera cutouts or system gesture bars:

CSS (style.css)

/* Header with adaptive padding for top notch */
.header {
    padding-top: env(safe-area-inset-top, 20px);
}

/* Bottom bar adapted for gestures */
.bottom-nav {
    padding-bottom: env(safe-area-inset-bottom, 20px);
}

/* Native touch feel */
body {
    -webkit-user-select: none;
    user-select: none;
    -webkit-tap-highlight-color: transparent;
    overscroll-behavior-y: none;
}

Hardware Native APIs (Phphone\Device)

Direct hardware access from native PHP without third-party plugins:

PHP (index.php)

use Phphone\Device;

// Capture Photo in Base64
$photo = Device::camera();

// Retrieve GPS Coordinates
$gps = Device::gps(); // ['lat' => 4.6097, 'lng' => -74.0817]

// Biometric Authentication (Face ID / Fingerprint)
if (Device::authenticate("Confirm your identity")) {
    Device::toast("Access Authorized");
}

// Haptic Vibration
Device::vibrate(200);

// Secure Keychain / Keystore Storage
Device::secureWrite("token", "my_secret_123");
$token = Device::secureRead("token");

PHP Method	Description	Return Type
`Device::camera()`	Opens native camera and captures a photo.	`string (Base64)`
`Device::gps()`	Retrieves precise GPS coordinates.	`array ['lat', 'lng']`
`Device::authenticate($msg)`	Requests Face ID or fingerprint prompt.	`bool`
`Device::vibrate($ms)`	Triggers haptic vibration response.	`void`
`Device::toast($message)`	Displays a native floating toast alert.	`void`
`Device::notification($title, $body)`	Displays an immediate local notification.	`void`
`Device::getContacts()`	Retrieves device contact list.	`array`

Push Notifications (Firebase FCM)

Phphone includes a unified push notification engine. Control behavior directly via backend JSON payloads:

Parameter	Type	Native Effect
`tag` / `id`	string	If specified, replaces/updates the previous notification (ideal for order tracking). If omitted, notifications stack.
`group` / `thread_id`	string	Groups multiple notifications under one collapsible card.
`reply`	bool	Enables inline "Direct Reply" text field within the system tray.

SQLite Database & Persistence

Read-Only Environment in Release APKs

In production Android APKs, the __DIR__ path is strictly read-only. For persistent SQLite storage, always write to the native writable path:

PHP Helper

function getDB() {
    $dataDir = __DIR__ . '/../../data';
    
    // Check if running inside Read-Only production package
    if (!is_writable(__DIR__)) {
        $temp = rtrim(sys_get_temp_dir(), '/\\');
        $dataDir = (strpos($temp, 'cache') !== false) 
            ? dirname($temp) . '/files/app_data' 
            : dirname($temp) . '/Documents/app_data';
    }
    
    if (!is_dir($dataDir)) @mkdir($dataDir, 0777, true);
    
    $pdo = new PDO('sqlite:' . $dataDir . '/database.sqlite');
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    return $pdo;
}

Background Workers (Daemons)

Execute headless background PHP tasks periodically via native foreground services:

JavaScript (Trigger)

// Start background daemon polling every 60 seconds
window.Kie.startDaemon(JSON.stringify({ 
    taskName: 'sync_data', 
    interval: 60 
}));

PHP (src/daemon.php)

<?php
$task = $_GET['task'] ?? 'unknown';
// Your background sync logic here (e.g. database replication)

Best Practices & Crash Prevention

Golden Rule: Prevent Zend Bailouts

The PHP engine stays alive in shared memory. NEVER execute exit; or die();, as doing so forces an immediate app crash. Always return or throw exceptions inside try/catch blocks.

POST Request Limitation in Release Mode

Due to Android WebView network interception constraints, POST request bodies are stripped in local file contexts. Always send payloads serialized as URL-encoded JSON via GET requests:

fetch('api.php?data=' + encodeURIComponent(JSON.stringify(payload)))

🐘 Documentación Oficial de Phphone

Glosario de Términos

Requisitos Previos

Instalación del CLI Global

En Windows (PowerShell Administrador):

En macOS / Linux:

Opción Alternativa (Vía Composer / Packagist):

Flujo de Trabajo Paso a Paso

1. Crear un Proyecto Nuevo (Con CLI Oficial)

2. Probar con Hot Reload

3. Personalizar Ícono y Pantalla de Carga (Splash)

4. Compilar para Producción (Release)

Ecosistema Frontend (TypeScript, Vite) & .phphoneignore

1. Flujo de Trabajo con Bundlers (Vite / TypeScript / Webpack)

2. El Archivo .phphoneignore (Preconfigurado de Fábrica)

Navegador Nativo Oculto (Dual WebView)

Manejo del Notch y Safe Areas (CSS)

APIs Nativas de Hardware (Phphone\Device)

Notificaciones Push (Firebase FCM)

Base de Datos SQLite y Persistencia

Tareas en Segundo Plano (Daemons)

Buenas Prácticas & Prevención de Errores

🐘 Official Phphone Documentation

Glossary of Terms

Prerequisites

Global CLI Installation

On Windows (PowerShell Administrator):

On macOS / Linux:

Alternative Setup (Via Composer / Packagist):

Step-by-Step Workflow

1. Create a New Project (Via Official CLI)

2. Test with Live Hot Reload

3. Customize App Icon and Splash Screen

4. Compile for Production (Release)

Frontend Toolchains (TypeScript, Vite) & .phphoneignore

1. Modern Bundlers Workflow (Vite / TypeScript / Webpack)

2. The .phphoneignore File (Preconfigured Out of the Box)

Background Native Browser (Dual WebView)

Notch & Safe Areas Handling (CSS)

Hardware Native APIs (Phphone\Device)

Push Notifications (Firebase FCM)

SQLite Database & Persistence

Background Workers (Daemons)

Best Practices & Crash Prevention

2. El Archivo `.phphoneignore` (Preconfigurado de Fábrica)

2. The `.phphoneignore` File (Preconfigured Out of the Box)