PHPackages                             athens/propel-js - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. athens/propel-js

ActivePropel-behavior[Database & ORM](/categories/database)

athens/propel-js
================

Interact with your Propel database, in JavaScript.

1.0.0(8y ago)43731[6 issues](https://github.com/AthensFramework/PropelJS/issues)MITPHP

Since Aug 29Pushed 8y ago2 watchersCompare

[ Source](https://github.com/AthensFramework/PropelJS)[ Packagist](https://packagist.org/packages/athens/propel-js)[ RSS](/packages/athens-propel-js/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (10)Dependencies (5)Versions (12)Used By (0)

PropelJS
========

[](#propeljs)

Interact with your [Propel](http://propelorm.org/) database, in JavaScript. PropelJS generates a JavaScript library from your Propel schema.

PropelJS is a behavior plugin for the [Propel](http://propelorm.org/) PHP ORM. You must be using Propel in order to use this package.

Example
=======

[](#example)

Write the following JavaScript:

```
var db = bookstore.propelJS({baseAddress:'/api/'});

// Retrieve a book and log its title.
db.books(2).get().then(
    function(book) {
        console.log(book.getTitle());
    }

// Create an author and a book they've written
db.authors()
    .setFirstName('John')
    .setLastName('Steinbeck Jr.')
    .save()
    .then(
        function(author) {
            db.books()
                .setTitle('Grapes of Wrath II')
                .setAuthorId(author.getId())
                .save();
        }
    );

// Remove a book from the database.
db.books(5).delete();

```

Given the following schema:

```

```

PropelJS creates the JavaScript library automatically every time you run `propel model:build`.

How it Works
============

[](#how-it-works)

PropelJS is a Propel database behavior. Each time you run `propel model:build`, it will generate a JavaScript library and an API handler class.

In your backend, you create an API endpoint which invokes the `::handle` method of the API handler class. In your frontend, you initialize a database connection to that endpoint. Then, all of your commands like `db.authors(3).get();`are routed through the API handler and Propel's database connection.

Brief Setup Guide
=================

[](#brief-setup-guide)

The following steps assume you're using [Composer](https://getcomposer.org/) and the [LAMP stack](https://en.wikipedia.org/wiki/LAMP_%28software_bundle%29). If you're not using Composer, then you can adapt these instructions to your own deployment environment.

1. Install PropelJS: Add `"athens/propel-js": "1.*"` to your Composer dependencies and run `composer update`.
2. Propel Schema: Add the `` between your `` tags. PropelJS is a *database* behavior, so it should *not* be placed inside `` tags.
3. Build Your Models: Run `propel model:build`. This creates a `generated-api/API.php` file and a `generated-js/your-db-name.js` file.
4. Add `API.php` to Autoload: Add `"generated-api/"` to your `composer.json` autoloading, alongside `"generated-classes/"`.
5. Create an API Endpoint: You now need to create a web-accessible directory to serve as your API endpoint. For example, the `api/` directory could be your API endpoint using the following `api/index.php` sample:

    ```
    require_once "/path/to/your/autoload.php";

    use \YourPropelProjectNamespace\API;

    echo API::handle();

    ```
6. Request Routing: All requests to your API (eg: `api/authors/2`) need to be routed to `api/index.php` by your webserver. Depending on your server configuration, the following `api/.htaccess` might work:

    ```
    RewriteEngine on
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d

    RewriteRule ^(.*)$ /absolute/path/to/api/index.php [L]

    ```
7. Include the JavaScript: You can either copy your `your-db-name.js` into a web accessible directory or you can configure your server to make the `generated-js/` directory web accessible. In either case, you'll need to include `your-db-name.js` and jQuery in your page headers:

    ```

    ```
8. Configure the Connection: Now you have to tell your JavaScript library where to find your API endpoint by configuring a database connection. For example:

    ```
    var db = bookstore.propelJS({baseAddress:'/api/'});

    ```

    You can read about more [configuration options](#connection-configuration).

That's it! The `db` variable is now your handle for communicating with the database. See [JavaScript Library Syntax](#javascript-library-syntax) for more information on how to use your auto generated library.

Detailed Example
================

[](#detailed-example)

This example demonstrates the basic steps that you'll need to complete to use PropelJS. We'll use the [LAMP stack](https://en.wikipedia.org/wiki/LAMP_%28software_bundle%29) plus [Composer](https://getcomposer.org/)for dependency management.

The specific details of this example may or may not work on your server, depending on its configuration. And I've chosen some details that favor easy security over easy deployment; adapt this example to your own practices.

This example will use the following project structure:

```
├── composer.json
├── propel.inc
├── schema.xml
├── generated-classes/
├── generated-migrations/
├── generated-sql/
├── vendor/
└── webroot/
    ├── about.php
    └── index.php

```

The `webroot/` directory will serve as the root of our web domain, with `index.php` and `about.php` addressed as `http://example.net/index.php` and `http://example.net/about.php`.

Step 1: Installation
--------------------

[](#step-1-installation)

This library is published on Packagist. To install using Composer, add the `"athens/propel-js": "1.*"` line to your `"require"` section:

```
{
    "require": {
        ...
        "athens/propel-js": "1.*",
        ...
    }
}

```

Step 2: Propel Schema
---------------------

[](#step-2-propel-schema)

PropelJS is a database-level behavior for Propel. To use it, you must insert `` into your database schema. For example:

```

```

Take note that `` should be placed inside your `` tags, but *not*inside your `` tags.

Step 3: Rebuild Your Models
---------------------------

[](#step-3-rebuild-your-models)

Perform a `propel model:build` as usual.

You should now have a `generated-api/` directory and a `generated-js/` directory living alongside your usual `generated-classes/` directory.

```
├── composer.json
├── propel.inc
├── schema.xml
├── generated-api/