> For the complete documentation index, see [llms.txt](https://uccello.gitbook.io/doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://uccello.gitbook.io/doc/the-basics/helpers.md).

# Helpers

## Definition

A helper is a php function you can use in all your application, in both controllers and views.

## Default helpers

### ucdomain()

Retrieves a domain by `id` or `slug`.

```php
use Uccello\Core\Models\Domain;

$domain = ucdomain(1);
echo $domain->name;
// => Uccello

echo ucdomain('uccello')->name;
// => Uccello

echo Domain::where('slug', 'uccello')->first()->name;
// => Uccello
```

### ucmodule()

Retrieves a module by `id` or `name`.

```php
use Uccello\Core\Models\Module;

$module = ucmodule(1);
echo $module->name;
// => user

echo ucmodule('user')->name;
// => user

echo Module::where('name', 'user')->first()->name;
// => user
```

{% hint style="danger" %}
As Uccello cache the modules, please don't use `ucmodule($moduleName)` in your migration files. Your new created module could be not accessible with this helper.\
Use `Module::where('name', $moduleName)->first()` instead.
{% endhint %}

### uctrans()

Retrieves the complete prefix of a label and translated it.\
If the translation does not exist, it tries to find a default one according to priorities.\
If no translation exist, it displays only the label without translation.

**Priority:**

1. Translation overridden in app
2. Translation in package
3. Default translation overridden in app
4. Default translation in uccello
5. No translation

```php
$personModule = ucmodule('person');
echo uctrans('field.first_name', $personModule);
// => First name (from resources/lang/en/person.php)

$userModule = ucmodule('user');
echo uctrans('block.general', $userModule); // This label is not translated in user module
// => General information (from vendor/uccello/uccello/resources/lang/en/default.php)

echo trans('uccello::default.block.general');
// => General information
```

### ucroute()

Retrieves a route and automatically adds domain and module params.

{% hint style="info" %}
The domain param is only added if the multi domains option is enabled.
{% endhint %}

```php
$domain = ucdomain('uccello');
$module = ucmodule('user');

echo ucroute('uccello.list', $domain, $module);
// => /uccello/user/list (with multi domains enabled)
// => /user/list (with multi domains disabled)

echo route('uccello.list', ['domain' => $domain->slug, 'module' => $module->name]);
// => /uccello/user/list (with multi domains enabled)
// => /user/list?domain=uccello (with multi domains disabled)

echo ucroute('uccello.detail', $domain, $module, ['id' => 1];
// => /uccello/user/detail?id=1 (with multi domains enabled)
// => /user/detail?id=1 (with multi domains disabled)
```

### uclog()

Displays log data into [Laravel Debug Bar](https://github.com/barryvdh/laravel-debugbar).

```php
uclog('My message'); // It's like uclog('My message', 'info');
uclog(\App\User::find(1), 'info');
uclog('Error message', 'error');
uclog('Warning message', 'warning');
```

### uitype()

Retrieves an uitype by `id` or `name`.

```php
use Uccello\Core\Models\Uitype;

echo uitype(1)->name;
// => text

echo uitype('text')->name;
// => text

echo Uitype::where('name', 'text')->name;
// => text
```

### displaytype()

Retrieves a display type by `id` or `name`.

```php
use Uccello\Core\Models\Displaytype;

echo displaytype(1)->name;
// => everywhere

echo displaytype('everywhere')->name;
// => everywhere

echo Displaytype::where('name', 'everywhere')->name;
// => everywhere
```

### capability()

Retrieves a capability by `id` or `name`.

```php
use Uccello\Core\Models\Capability;

echo capability(1)->name;
// => retrieve

echo capability('retrieve')->name;
// => retrieve

echo Capability::where('name', 'retrieve')->name;
// => retrieve
```

### ucasset()

Returns the complete path of an asset available in an external package.

```php
echo ucasset('js/app.js');
// => public/vendor/uccello/uccello/js/app.js

echo usasset('js/app.js', 'uccello/uccello');
// => public/vendor/uccello/uccello/js/app.js

echo usasset('js/app.js', 'acme/my-package');
// => public/vendor/acme/my-package/js/app.js
```

### ucattribute()

Returns a record attribute value. It is able to follow a complex path according to models definition (e.g. 'domain.parent.name'). If the attribute is not accessible, it returns `null`.

```php
$user = auth()->user();

// The ACME domain is a child of Uccello domain.
$acmeUser = \App\User::where('domain_id', ucdomain('acme'))->first();

echo ucattribute($user, 'domain.name');
// => Uccello

echo ucattribute($user, 'domain.parent.name');
// => null

echo ucattribute($acmeUser, 'domain.parent.name');
// => Uccello
```

{% hint style="info" %}
To be able to use this helper, you have to define the `belongsTo` relations in the different models.
{% endhint %}

### ucnotify()

Displays a flash info [toast](https://materializecss.com/toasts.html) containing the message of your choice.

```php
ucnotify('My message'); // Displays a black info toast
ucnotify('Info message', 'info'); // Displays a black info toast
ucnotify('Success message', 'success'); // Displays a green success toast
ucnotify('Warning message', 'warning'); // Displays an orange warning toast
ucnotify('Error message', 'error'); // Displays a red error toast
```

### ucrecord()

Retrieves a record by `id` or `uuid`. If you want to retrieves a record by its `id`, you have to specify its `model class` two.

{% hint style="info" %}
All records have an `uuid` defined in the database table called by default `uccello_entities`.
{% endhint %}

```php
// Retrieve by uuid
$record = ucrecord('00013d27-1195-4bcc-b05d-ee63e2aaa471');

// Retrieve by id and model class
$record = ucrecord(1, \App\User::class);
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://uccello.gitbook.io/doc/the-basics/helpers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.