# Installation - [Creating a Hypervel Application](#creating-a-hypervel-application) - [Requirements](#requirements) - [Creating an Application](#creating-an-application) - [Watching for Changes](#watching-for-changes) - [Starter Kits](#starter-kits) - [Initial Configuration](#initial-configuration) - [Environment Based Configuration](#environment-based-configuration) - [Databases and Migrations](#databases-and-migrations) - [Directory Configuration](#directory-configuration) - [IDE Support](#ide-support) - [Static Analysis](#static-analysis) - [Next Steps](#next-steps) - [Hypervel the Full Stack Framework](#hypervel-the-fullstack-framework) - [Hypervel the API Backend](#hypervel-the-api-backend) ## Creating a Hypervel Application ### Requirements Hypervel supports Linux and macOS. Windows developers should use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install). Native Windows execution is not supported. Before creating your first Hypervel application, make sure that your local machine has [PHP](https://php.net), [Composer](https://getcomposer.org), and the Swoole PHP extension installed. In addition, you should install either [Node and NPM](https://nodejs.org) or [Bun](https://bun.sh/) so that you can compile your application's frontend assets. The Hypervel framework has a few system requirements:
- PHP >= 8.4 - Composer - cURL PHP Extension - Fileinfo PHP Extension - Filter PHP Extension - Hash PHP Extension - Intl PHP Extension - JSON PHP Extension - Mbstring PHP Extension - OpenSSL PHP Extension - PCNTL PHP Extension - PDO PHP Extension - POSIX PHP Extension - Session PHP Extension - Swoole PHP Extension >= 6.3.0RC1 - Tokenizer PHP Extension
> [!WARNING] > Hypervel supports only the official [Swoole](https://github.com/swoole/swoole-src) extension. Forks such as OpenSwoole aren't supported. The Hypervel team actively contributes enhancements and fixes to Swoole, and Hypervel depends on several of those changes. If your application uses Redis for cache, queues, sessions, or broadcasting, you should also install the Redis PHP extension 6.1 or higher. If it uses MySQL or MariaDB, the PDO MySQL extension must use PHP's mysqlnd driver, which is the default. You may install Swoole using [PIE](https://github.com/php/pie): ```shell pie install "swoole/swoole:^6.3.0@RC" --enable-openssl --enable-swoole-curl --enable-swoole-sqlite --enable-swoole-pgsql ``` Swoole must be built with OpenSSL and native cURL support. The SQLite and PostgreSQL options are required to use those databases. Each option needs the matching development library (OpenSSL, libcurl, SQLite, or libpq) when Swoole is compiled. Applications using FTP disks also need `--enable-swoole-ftp`; see [FTP configuration](/docs/{{version}}/filesystem#ftp-driver-configuration). Once the Homebrew formula provides a Swoole version that meets the requirement above, macOS developers may install Swoole via Homebrew instead. The formula already includes the required build options. Replace `8.4` with your installed PHP version: ```shell brew tap shivammathur/extensions brew install shivammathur/extensions/swoole@8.4 ``` You should also ensure that `swoole.use_shortname` is disabled in your `php.ini` file: ```ini swoole.use_shortname=Off ``` Hypervel will not start while Swoole short function names are enabled. Disabling them ensures Hypervel's namespaced coroutine helpers and exception handling work correctly. Hypervel also will not start if Swoole was built without OpenSSL or native cURL support, and SQLite or PostgreSQL connections fail if Swoole was built without support for that database. #### Incompatible Extensions Because Hypervel is based on Swoole's coroutine functionality, some extensions are incompatible with the coroutine runtime. The following extensions are currently incompatible:
- xhprof - blackfire - trace - uopz
Xdebug support depends on your PHP and Swoole versions. If you experience coroutine or server issues while debugging, disable Xdebug and retry the request. ### Creating an Application After you have installed PHP, Composer, and Swoole, you are ready to create a new Hypervel application using Composer's `create-project` command: ```shell composer create-project hypervel/hypervel example-app ``` Once the application has been created, you can start Hypervel's local development server using the `serve` Artisan command: ```shell cd example-app php artisan serve ``` Once you have started the development server, you can access your application in your web browser at [http://localhost:8000](http://localhost:8000). The server host, port, worker count, and other Swoole options may be configured in your application's `config/server.php` file. You may temporarily override the HTTP server address for the current process using the `--host` and `--port` options: ```shell php artisan serve --host=127.0.0.1 --port=8001 ``` The `--host` option also accepts a port, such as `127.0.0.1:8001` or `[::1]:8001`. If both options specify a port, `--port` takes precedence. ### Watching for Changes Because Hypervel runs your application in a long-lived process, you should restart the server after making code changes. During development, you may use the `watch` command instead of `serve` to start the server and restart it automatically when files change: ```shell php artisan watch ``` You may customize the watched paths in your application's `config/watcher.php` file, or pass extra paths using the `--path` option: ```shell php artisan watch --path=routes --path="database/**/*.php" ``` For more information about configuring watch paths and drivers, consult the [file watching documentation](/docs/{{version}}/watcher). If your application uses frontend assets, install and build them using your JavaScript package manager: ```shell npm install npm run build ``` Of course, you may also want to [configure a database](#databases-and-migrations). ### Starter Kits If you would like a head start when developing your Hypervel application, consider using one of our [starter kits](/docs/{{version}}/starter-kits). Hypervel starter kits provide backend and frontend authentication scaffolding for your new application. For a minimal Blade application, start with the standard Hypervel application skeleton: ```shell composer create-project hypervel/hypervel example-app ``` If you would like to build your frontend using Inertia and React, use the React application starter kit: ```shell composer create-project hypervel/react-starter-kit example-app ``` ## Initial Configuration All configuration files for the Hypervel framework are stored in the `config` directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you. Hypervel needs almost no additional configuration out of the box. You are free to get started developing! However, you may wish to review the `config/app.php` and `config/server.php` files and their documentation. These files contain options such as your application's URL, locale, server host, server port, and worker count. ### Environment Based Configuration Since many of Hypervel's configuration option values may vary depending on whether your application is running on your local machine or on a production server, many important configuration values are defined using the `.env` file that exists at the root of your application. Your `.env` file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration. Furthermore, this would be a security risk in the event an intruder gains access to your source control repository, since any sensitive credentials would be exposed. > [!NOTE] > For more information about the `.env` file and environment based configuration, check out the full [configuration documentation](/docs/{{version}}/configuration#environment-configuration). ### Databases and Migrations Now that you have created your Hypervel application, you probably want to store some data in a database. By default, your application's `.env` configuration file specifies that Hypervel will be interacting with an SQLite database. During the creation of the application, Hypervel created a `database/database.sqlite` file for you, and ran the necessary migrations to create the application's database tables. If you prefer to use another database driver such as MySQL or PostgreSQL, you can update your `.env` configuration file to use the appropriate database. For example, if you wish to use MySQL, update your `.env` configuration file's `DB_*` variables like so: ```ini DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=hypervel DB_USERNAME=root DB_PASSWORD= ``` If you choose to use a database other than SQLite, you will need to create the database and run your application's [database migrations](/docs/{{version}}/migrations): ```shell php artisan migrate ``` ### Directory Configuration Hypervel should be served by its Swoole-based application server. In production, a web server such as Nginx should serve your application's static files directly and proxy dynamic requests to the Hypervel server. You should not attempt to serve a Hypervel application directly out of a subdirectory of your web server's document root, as doing so could expose sensitive files present within your application. ## IDE Support You are free to use any code editor you wish when developing Hypervel applications. If you're looking for lightweight and extensible editors, [VS Code](https://code.visualstudio.com) or [Cursor](https://cursor.com) provide a great editing experience for PHP, JavaScript, and TypeScript projects. For extensive and robust PHP support, take a look at [PhpStorm](https://www.jetbrains.com/phpstorm/), a JetBrains IDE. PhpStorm includes powerful code completion, refactoring, navigation, and debugging tools for PHP applications. Hypervel's application skeleton includes the `swoole/ide-helper` package in development so IDEs can understand Swoole classes, constants, and functions. ### Static Analysis The application skeleton includes PHPStan with the `hypervel/phpstan` extension, which boots your application so PHPStan understands its models, container services, configuration and other framework features. Run `composer analyse` to check your application. To add the extension to an existing application, or to learn about its checks and configuration, see the [static analysis documentation](/docs/{{version}}/static-analysis). ## Next Steps Now that you have created your Hypervel application, you may be wondering what to learn next. First, we strongly recommend becoming familiar with how Hypervel works by reading the following documentation:
- [Request Lifecycle](/docs/{{version}}/lifecycle) - [Configuration](/docs/{{version}}/configuration) - [Directory Structure](/docs/{{version}}/structure) - [Frontend](/docs/{{version}}/frontend) - [Service Container](/docs/{{version}}/container) - [Facades](/docs/{{version}}/facades) - [Coroutines](/docs/{{version}}/coroutines) - [Deployment](/docs/{{version}}/deployment)
How you want to use Hypervel will also dictate the next steps on your journey. There are a variety of ways to use Hypervel, and we'll explore two primary use cases for the framework below. ### Hypervel the Full Stack Framework Hypervel may serve as a full stack framework. By "full stack" framework we mean that you are going to use Hypervel to route requests to your application and render your frontend via [Blade templates](/docs/{{version}}/blade) or a single-page application hybrid technology like [Inertia](/docs/{{version}}/inertia). This is the most common way to use the Hypervel framework, and, in our opinion, the most productive way to use Hypervel. If this is how you plan to use Hypervel, you may want to check out our documentation on [frontend development](/docs/{{version}}/frontend), [routing](/docs/{{version}}/routing), [views](/docs/{{version}}/views), or the [Eloquent ORM](/docs/{{version}}/eloquent). Hypervel includes first-class support for Blade and Inertia, and our React starter kit provides a fast path to a full-stack Inertia application. If you are using Hypervel as a full stack framework, we also strongly encourage you to learn how to compile your application's CSS and JavaScript using [Vite](/docs/{{version}}/vite). > [!NOTE] > If you want to get a head start building your application, check out one of our official [application starter kits](/docs/{{version}}/starter-kits). ### Hypervel the API Backend Hypervel may also serve as an API backend to a JavaScript single-page application, mobile application, or another service. In this context, you may use Hypervel to provide authentication, data storage / retrieval, queues, WebSocket services, scheduled jobs, notifications, and more. If this is how you plan to use Hypervel, you may want to check out our documentation on [routing](/docs/{{version}}/routing), [Hypervel Sanctum](/docs/{{version}}/sanctum), [queues](/docs/{{version}}/queues), [broadcasting](/docs/{{version}}/broadcasting), and the [Eloquent ORM](/docs/{{version}}/eloquent).