AdonisJS Legacy Documentation

The AdonisJS documentation is written using Asciidoc. The source files are maintained in this repository, but they are compiled and rendered by the adonisjs/adonisjs.com repository, which is itself an AdonisJS application.

To view the live documentation, visit http://adonisjs.com/docs.

You can interact with the AdonisJs team and community through the following channels:

• GitHub Repositories: Share bugs or create feature requests.
• Forum: Ask questions, showcase projects, and participate in framework discussions.
• Discord: Join the server for instant chat with the community.
• Twitter: Stay informed about progress and community projects.

Lucid is the AdonisJS implementation of the Active Record pattern. It provides an expressive API for managing database data, relationships, and lifecycles. Lucid models are stored in the app/Models directory, where each model typically represents a database table (e.g., a User model maps to a users table).

Key features include:

• Transparent fetching and persisting of data.
• Relationship management (e.g., hasOne, hasMany).
• Lifecycle hooks and Getters/Setters.
• Data serialization and date management.

The AdonisJs Query Builder provides a unified JavaScript syntax to interact with SQL databases. It abstracts away connection-specific syntax, allowing you to write code that is compatible across different SQL dialects (e.g., migrating from MySQL to PostgreSQL) without rewriting queries. It also facilitates building incremental, conditional queries more cleanly than raw string concatenation.

const Database = use('Database')

class UserController {
  async index (request, response) {
    return await Database
      .table('users')
      .where('username', 'john')
      .first()
  }
}

When using a database (e.g., via Lucid) inside an Ace command, you must manually close the connection before the command finishes. If you do not, the process will not exit.

const Database = use('Database')

async handle (args, options) {
  // ... database logic ...
  
  // Crucial: prevent the command from hanging
  Database.close()
}

const Database = use('Database')

class Quote extends Command {
  async handle (args, options) {
    let quote = await Quote.query().orderByRaw('rand()').first()
    console.log(quote.content)

    Database.close()
  }
}

The app directory contains the core business logic of your application and is autoloaded under the App namespace. It is subdivided into several functional directories, most of which are automatically created via AdonisJs CLI commands:

• app/Commands: CLI commands (created via adonis make:command <name>).
• app/Controllers: HTTP and WebSocket controllers (created via adonis make:controller <name>).
• app/Exceptions: Global exception handler and custom exceptions (created via adonis make:ehandler or adonis make:exception <name>).
• app/Listeners: Event listeners (created via adonis make:listener <name>).
• app/Middleware: Middleware (created via adonis make:middleware <name>).
• app/Models: Data models (created via adonis make:model <name>).
• app/Validators: Route validators (created via adonis make:validator <name>; requires the Validator Provider).

Controllers are classes used to group related request handling logic. They act as the interaction point between models, views, and other services.

Key Principles:

• Single Responsibility: A controller's only job is to respond to an HTTP request.
• No Internal Usage: Do not require controllers inside other files to use them internally; they should only be accessed via routes.
• Context Injection: Controller methods act as route handlers and automatically receive the HTTP Context as an argument, providing access to request, response, and other lifecycle objects.

'use strict'

class UserController {
  index ({ request, response }) {
    // Access request and response from the HTTP Context
  }
}

module.exports = UserController

Since HTML forms only support GET and POST methods, AdonisJs allows you to perform resourceful operations (like PUT or DELETE) by using form method spoofing.

To use this, append ?_method=METHOD to the form's action URL. AdonisJs will only spoof the method if the original request is a POST.

To disable this feature, set allowMethodSpoofing: false in config/app.js under the http key.

// Route definition
Route.put('/users/:id', 'UserController.update')

// HTML View
<form action="/users/1?_method=PUT" method="POST">
</form>

Query scopes allow you to extract query constraints into reusable methods. Define them using the scope prefix in your model.

Definition:

class User extends Model {
  static scopeHasProfile (query) {
    return query.has('profile')
  }
}

Usage: When calling the scope, drop the scope prefix and use camelCase.

const users = await User.query().hasProfile().fetch()