Versionable

https://github.com/mpociot/versionable
Admin
Versionable is a Laravel package that provides automatic model versioning, history tracking, and...
Tokens:8,188
Snippets:72
Trust Score:9.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install pgloader with apt-get

Source: https://github.com/mpociot/versionable/blob/master/README.md

Installs pgloader on a local machine or server using the apt-get package manager. Required before using pgloader for bulk data import.

```bash
apt-get install pgloader
```

--------------------------------

### Example: Create initial versions for all User rows

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/versionable-trait.md

Calls initializeVersions() on the User model to create an initial version for every existing row.

```php
// Create an initial version for every existing User row
User::initializeVersions();
```

--------------------------------

### setReasonAttribute() usage example

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/versionable-trait.md

Sets the reason for the next version using the Eloquent mutator. The reason is stored on the next created version and can be retrieved via currentVersion()->reason. The example shows setting the reason and then updating the model.

```php
$user = User::find(1);
$user->reason = 'Fixed the typo in the profile';
$user->update(['name' => 'John']);

echo $user->currentVersion()->reason; // "Fixed the typo in the profile"
```

--------------------------------

### disableVersioning() usage example

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/versionable-trait.md

Disables version creation for the current model instance until enableVersioning() is called. Useful for bulk updates where you do not want a version per change. The example shows that after calling disableVersioning(), an update does not create a version entry, and versioning resumes after enableVersioning().

```php
$user = User::find(1);
$user->disableVersioning();

$user->update(['some_attribute' => 'changed value']);
// No version entry is created.

$user->enableVersioning(); // versioning resumes
```

--------------------------------

### boot() method signature

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/service-provider.md

Signature of the boot() method. Declares two publishable groups: 'config' and 'migrations'.

```php
public function boot()
```

--------------------------------

### initializeVersions() method signature

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/versionable-trait.md

Static helper for retrofitting versioning onto existing data. Iterates over all instances and calls createInitialVersion() on each. Safe to run repeatedly because createInitialVersion() skips models that already have versions.

```php
public static function initializeVersions()
```

--------------------------------

### pgloader configuration file (config.load)

Source: https://github.com/mpociot/versionable/blob/master/README.md

Configuration file for pgloader that specifies the source database and target Supabase database. Includes performance settings: wal_buffers='64MB', max_wal_senders=0, statement_timeout=0, work_mem='2GB'.

```plaintext
LOAD DATABASE
    FROM sourcedb://USER:PASSWORD@HOST/SOURCE_DB
    INTO postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres
ALTER SCHEMA 'public' OWNER TO 'postgres';
set wal_buffers = '64MB', max_wal_senders = 0, statement_timeout = 0, work_mem to '2GB';
```

--------------------------------

### Run pgloader with configuration file

Source: https://github.com/mpociot/versionable/blob/master/README.md

Executes pgloader using the configuration file (config.load) to perform the data import.

```bash
pgloader config.load
```

--------------------------------

### register() method signature

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/service-provider.md

Signature of the register() method. It merges the package config so defaults are available immediately.

```php
public function register ()
```

--------------------------------

### Merge package config in register()

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/service-provider.md

Merges the package config file into the 'versionable' key. After this, config('versionable.version_model') resolves to Mpociot\Versionable\Version::class unless overridden.

```php
$this->mergeConfigFrom(__DIR__.'/../../../config/config.php', 'versionable');
```

--------------------------------

### new Version()

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

Creates a new Version model instance. It inherits the standard Eloquent constructor and is typically instantiated by the trait, but can be called directly with optional attributes.

```APIDOC
## new Version()

### Description
Creates a new Version model instance. It inherits the standard Eloquent constructor and is typically instantiated by the trait, but can be called directly with optional attributes.

### Method
Constructor

### Signature
`new Version(array $attributes = [])`

### Parameters
- **attributes** (array) - Optional - Attributes to set on the model.

### Request Example
```php
new Version()
new Version(['reason' => 'manual version'])
```

### Notes
To build a model instance from a stored version, use `getModel()`.
```

--------------------------------

### Artisan commands for migrations and config publishing

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/service-provider.md

Artisan commands to run the migration without publishing, publish and migrate, and publish the config file. The loadMigrationsFrom call is commented out, so migrations run only when published or executed explicitly.

```bash
# Run the shipped migration without publishing it
php artisan migrate --path=vendor/mpociot/versionable/src/migrations
```

```bash
# Publish and customize the migration, then migrate
php artisan vendor:publish --provider="Mpociot\Versionable\Providers\ServiceProvider" --tag="migrations"
php artisan migrate
```

```bash
# Publish the config file for customization
php artisan vendor:publish --provider="Mpociot\Versionable\Providers\ServiceProvider" --tag="config"
```

--------------------------------

### Publish config file

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/service-provider.md

Publishes the config file to config_path('versionable.php') under the 'config' tag.

```php
$this->publishes([
    __DIR__.'/../../../config/config.php' => config_path('versionable.php'),
], 'config');
```

--------------------------------

### Version constructor usage with optional attributes

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

The Version model inherits the standard Eloquent constructor, so it can be instantiated without arguments or with an array of attributes such as 'reason'. It is normally instantiated by the trait rather than application code.

```php
new Version()
new Version(['reason' => 'manual version'])
```

--------------------------------

### diff(?Version $againstVersion = null)

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

Compares this version against another version (or the current model state if null) and returns an associative array of attributes whose values differ. Timestamps are excluded from the result.

```APIDOC
## `diff(?Version $againstVersion = null)`

### Description
Compares this version against another version (or the current model state if null) and returns an associative array of attributes whose values differ. Timestamps are excluded from the result.

### Method
`diff`

### Signature
```php
public function diff(?Version $againstVersion = null)
```

### Parameters
- **$againstVersion** (`Version` or `null`) - Optional - The version to compare against. When `null`, the diff is computed against the versioned model's **current** version (via `$this->versionable()->withTrashed()->first()->currentVersion()->getModel()`), i.e. "changed since I was created".

### Returns
- **array** - Associative array keyed by attribute name whose values **differ between the two compared models**; keys where both models have equal values are absent. Returns an empty array for identical models. Diff is computed with `array_diff_assoc($againstModelAttributes, $thisModelAttributes)` ($againstVersion as source, this version as comparison), so the values are the *other* model's values for the differing keys.

### Throws
None.

### Notes
Timestamps are removed from the result: the created-at column, the updated-at column, and — when the model supports soft deletes — the deleted-at column.

### Example (basic — diff against the current version)
```php
// What changed between the previous version and the current model state?
$diff = $page->previousVersion()->diff();
```

### Example (specific pair)
```php
$oldest  = $user->versions()->orderBy('version_id', 'ASC')->first();
$diff    = $user->currentVersion()->diff($oldest);

foreach ($diff as $attribute => $value) {
    echo "{$attribute}: changed\n";
}
```

Returned array shape: `['name' => 'John', 'email' => 'j@example.com']`. In the first example, `$page->previousVersion()->diff()` returns the *current* values of attributes that differ from what the previous version stored.
```

--------------------------------

### Version model table and primary key properties

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

Defines the custom table name 'versions' and primary key 'version_id' for the Version model.

```php
public $table = "versions";
protected $primaryKey = "version_id";
```

--------------------------------

### Publish migrations

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/service-provider.md

Publishes the contents of src/migrations/ to database_path('/migrations') under the 'migrations' tag.

```php
$this->publishes([
    __DIR__ . '/../../../migrations/' => database_path('/migrations'),
], 'migrations');
```

--------------------------------

### macOS helper stdin JSON context

Source: https://github.com/mpociot/versionable/blob/master/README.md

JSON object passed to the macOS helper on stdin, containing schema version, command name, candidate pid, and daemon context. The helper must print the daemon's pid on stdout.

```json
{
  "schema_version": 1,
  "command": "<command name>",
  "candidate_pid": 48213,
  "workdir": "/abs/session/workdir",
  "daemon_cwd": "/abs/daemon/cwd",
  "daemon_argv": ["/path/to/daemon", "..."],
  "daemon_env": { "SOME_KEY": "value" }
}
```

--------------------------------

### versionablePreSave() method signature

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/versionable-trait.md

Protected method invoked by the saving event. When versioning is enabled, it stores the dirty attributes and records the updating flag.

```php
protected function versionablePreSave()
```

--------------------------------

### Register ServiceProvider in config/app.php

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/service-provider.md

Manual registration of the service provider in Laravel 5.x's config/app.php. Required only if package auto-discovery is not used.

```php
// config/app.php (Laravel 5.x manual registration)
'providers' => [
    Mpociot\Versionable\Providers\ServiceProvider::class,
],
```

--------------------------------

### diff() method signature

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

Signature of the diff method. Accepts an optional Version instance; when null, the diff is computed against the versioned model's current version.

```php
public function diff(?Version $againstVersion = null)
```

--------------------------------

### Diff against current version

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

Computes the diff between the previous version and the current model state. Returns an associative array of differing attributes with the current values.

```php
// What changed between the previous version and the current model state?
$diff = $page->previousVersion()->diff();
```

--------------------------------

### versionablePostSave() method signature

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/versionable-trait.md

Protected method invoked by the saved event. Creates and persists a version row when versioning is enabled and the save is an update or insert with dirty data. The version row includes model data and user ID, then purges old versions.

```php
protected function versionablePostSave()
```

--------------------------------

### Access responsible user from version

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

The responsible_user accessor returns the user who created the version, resolved from the configured auth provider model. Returns null if no user is found.

```php
$version = $content->currentVersion();

if ($version->responsible_user) {
    echo $version->responsible_user->name . ' made this change';
}
```

--------------------------------

### Diff against a specific version

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

Computes the diff between the current version and a specific older version. Iterates over the returned array to print each changed attribute.

```php
$oldest  = $user->versions()->orderBy('version_id', 'ASC')->first();
$diff    = $user->currentVersion()->diff($oldest);

foreach ($diff as $attribute => $value) {
    echo "{$attribute}: changed\n";
}
```

--------------------------------

### Retrieve current model from a version

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

Use the versionable() relation to access the currently-stored versioned model from a Version instance. Because the model may be deleted, chaining withTrashed() is common.

```php
$version = Version::find(100);
$currentModel = $version->versionable; // the model as it exists now
```

--------------------------------

### versionable()

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

Returns the polymorphic owner of the version, i.e., the currently-stored versioned model. This is the inverse of the trait's versions() relation.

```APIDOC
## versionable()

### Description
Returns the polymorphic owner of the version, i.e., the currently-stored versioned model. This is the inverse of the trait's versions() relation.

### Method
versionable()

### Signature
`public function versionable()`

### Parameters
None

### Returns
`Illuminate\Database\Eloquent\Relations\MorphTo` - The polymorphic owner (`morphTo()`), morph name `versionable`.

### Throws
None

### Example
```php
$version = Version::find(100);
$currentModel = $version->versionable; // the model as it exists now
```

### Notes
Because the versioned model may have been deleted since the version was created, chaining `withTrashed()` is a common pattern (see `diff()`).
```

--------------------------------

### getResponsibleUserAttribute()

Source: https://github.com/mpociot/versionable/blob/master/_autodocs/api-reference/version.md

Eloquent accessor for the `responsible_user` attribute, returning the user who created the version. The user class is resolved from the configured auth provider model.

```APIDOC
## getResponsibleUserAttribute()

### Description
Eloquent accessor for the `responsible_user` attribute, returning the user who created the version. The user class is resolved from the configured auth provider model.

### Method
getResponsibleUserAttribute()

### Signature
`public function getResponsibleUserAttribute()`

### Parameters
None

### Returns
`mixed` - The user model instance, or `null`. Resolution: `Config::get("auth.providers.users.model")::find($this->user_id)`.

### Throws
None

### Example
```php
$version = $content->currentVersion();

if ($version->responsible_user) {
    echo $version->responsible_user->name . ' made this change';
}
```
```
Tokens:
Raw