Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/raczkodavid/Zooniverse/llms.txt

Use this file to discover all available pages before exploring further.

Animals are the individual creatures housed within enclosures in Zooniverse. Each animal belongs to exactly one enclosure at a time, carries a type (predator or herbivore) that must match the other animals in that enclosure, and can optionally have a photo. Admins manage the full animal lifecycle; archived (soft-deleted) animals are retained in the database and can be restored to a compatible enclosure at any time.

​
Animal fields

The animals table stores the following columns:
FieldTypeRequiredDescription
namestringYesThe animal’s individual name.
speciesstringYesThe species (e.g. "Lion", "Zebra").
is_predatorbooleanYestrue for predators, false for herbivores.
born_attimestampYesThe animal’s date and time of birth.
image_namestringNoOriginal filename of the uploaded image.
image_name_hashstringNoHashed filename used for storage on disk.
enclosure_idunsignedBigIntegerNoForeign key to the assigned enclosure. Set to null when archived.
deleted_attimestampNoPopulated on soft-delete (archive). null for active animals.

​
Adding an animal

Only admins can create animals. Navigate to GET /animals/create or use the Add Animal action.
1

Fill in the animal details

Complete the form with the following fields:
  • Name — the animal’s individual name (required string).
  • Species — the species name (required string).
  • Animal type — choose Predator or Herbivore from the dropdown (required).
  • Born At — select a datetime using the datetime-local picker (required).
  • Image — upload an optional photo (any image file type via accept="image/*").
2

Select an enclosure

Click Select Enclosure to open the enclosure picker modal. The dropdown colour-codes available enclosures:
  • Green — empty enclosure (accepts either type).
  • Red — predator enclosure.
  • No highlight — herbivore enclosure.
Select the enclosure the animal should be placed in and close the modal.
3

Submit

Click Create Animal. The server validates the input, runs compatibility and capacity checks, optionally stores the image, and creates the animal record. You are redirected to the enclosure’s detail page.

​
Validation rules

'name'         => 'required|string',
'species'      => 'required|string',
'type'         => 'required|in:predator,herbivore',
'born_at'      => 'required|date|before:now|after:01-01-1900',
'enclosure_id' => 'required|exists:enclosures,id',
The born_at field must be a valid date that is before the current date and time and after 1 January 1900. Future dates and dates before 1900 are rejected.

​
Compatibility and capacity checks

After field validation the server performs two additional checks before saving.

​
Type compatibility

The selected enclosure must be compatible with the animal’s type: 
if ($enclosure->isPredatorEnclosure() !== null && $isPredator !== $enclosure->isPredatorEnclosure()) {
    return redirect()->back()
        ->withErrors(['enclosure_id' => 'The selected enclosure is not compatible with the animal type.'])
        ->withInput();
}
You cannot place a predator in a herbivore enclosure or a herbivore in a predator enclosure. An enclosure’s type is set by its first animal. Empty enclosures (returning null from isPredatorEnclosure()) accept either type.

​
Capacity check

The enclosure must not already be full: 
if ($enclosure->isFull()) {
    return redirect()->back()
        ->withErrors(['enclosure_id' => 'The selected enclosure is full.'])
        ->withInput();
}
Use Animal::getValidEnclosures() when you need to retrieve only the enclosures that are both compatible with a given animal’s type and not yet at capacity. This is used internally when building the restore form for archived animals.

​
Image upload

The image field is optional. When a file is provided:
  1. The original filename is saved to image_name.
  2. A hashed filename is generated ($image->hashName()) and saved to image_name_hash.
  3. The file is stored in the public disk under the images/ directory:
$image->storeAs('images', $imageHash, 'public');
Images are served from storage/images/{image_name_hash}. If no image is uploaded, a placeholder image is displayed in the enclosure detail view.

​
Editing an animal

Only admins can edit animals. Navigate to GET /animals/{id}/edit or click Edit on an animal in the enclosure detail view. The edit form is identical to the create form and applies the same validation rules and compatibility/capacity checks.
When editing, the capacity check runs against the target enclosure, not the animal’s current enclosure. If the animal is staying in its current enclosure and that enclosure is full, the edit will be rejected unless you are not changing the enclosure. Plan moves accordingly.

​
Image replacement

If a new image is uploaded during an edit:
  1. The old image is deleted from storage:
Storage::disk('public')->delete('images/' . $imageHash);
  1. The new file is stored with a freshly generated hash, and both image_name and image_name_hash are updated on the record.
If no new image is uploaded, the existing image is kept unchanged.

​
Archiving (soft-delete) an animal

Click Archive on an animal in the enclosure detail view. This sends a DELETE /animals/{id} request. Archiving does not permanently remove the animal. The controller:
  1. Sets enclosure_id to null, removing the animal from its enclosure.
  2. Calls $animal->delete(), which triggers Laravel’s SoftDeletes trait and populates deleted_at.
$animal->enclosure_id = null;
$animal->save();
$animal->delete(); // soft-delete
Archived animals are no longer counted towards an enclosure’s animal count and do not appear in the enclosure detail view. However, they remain in the database and are recoverable by an admin.

​
Restoring an archived animal

Admins can view all archived animals at GET /animals/archived. The list is ordered by deleted_at descending (most recently archived first). To restore an animal:
1

Select a target enclosure

Choose a compatible, non-full enclosure from the restore form for that animal.
2

Submit

Send a POST /animals/{id}/restore request. The server checks type compatibility and capacity using the same logic as creation. If both pass, enclosure_id is set and the deleted_at timestamp is cleared.
$animal->enclosure_id = $request->enclosure_id;
$animal->restore();

Build docs developers (and LLMs) love

Get started for freeTalk to us