Method Documentation: findMany

Purpose

The findMany method is engineered to retrieve multiple User records meeting specified filter criteria. It accommodates a variety of query capabilities, including filtering, sorting, pagination, selective field returns, cursor-based pagination, and the inclusion of related models. This method ensures efficiency and flexibility in data retrieval operations, returning an empty array if no Users match the criteria.

Parameters

array $criteria = [] - An associative array detailing the query parameters. Includes filters ('where'), order ('orderBy'), pagination limits ('take'), pagination skips ('skip'), cursor for pagination ('cursor'), field selection ('select'), related model inclusion ('include'), and ensuring distinct records ('distinct').
bool $format = false- Optional. Specifies the format of the returned data ('false' or 'true') by default is array, but can also be set to 'true' for object format.

Return Value

Returns an array of User data matching the specified criteria, formatted according to the $format parameter. Returns an empty array if no matching records are found.

Exception Handling

Throws an exception if 'include' and 'select' parameters are used simultaneously or if the criteria provided for query execution are invalid. This ensures the method's reliability and secure data retrieval.

Features

Facilitates complex queries with support for filtering, sorting, pagination, and more.
Enables selective field retrieval and related model inclusion for customized data fetching.
Supports cursor-based pagination for advanced navigation through datasets.
Guarantees secure query execution with robust input validation.
Ensures the retrieval of distinct records to prevent duplicate results.

Example Usage: Default Call

  use Lib\Prisma\Classes\Prisma;

    $prisma = Prisma::getInstance();
    $users = $prisma->user->findMany();

    echo "<pre>";
    echo "User found: " . print_r($users, true);
    echo "</pre>";

Example Usage: Applying Filters and Pagination

  use Lib\Prisma\Classes\Prisma;

    $prisma = Prisma::getInstance();
    $users = $prisma->user->findMany([
        'distinct' => true,
        'take' => 10,
        'skip' => 0,
        'orderBy' => ['name' => 'asc'],
    ]);

    echo "<pre>";
    echo "User found: " . print_r($users, true);
    echo "</pre>";

Example Usage: Filtering with Conditions

  use Lib\Prisma\Classes\Prisma;

    $prisma = Prisma::getInstance();
    $users = $prisma->user->findMany([
        'where' => ['name' => 'John Doe'],
        'distinct' => true,
        'take' => 10,
        'skip' => 0,
        'orderBy' => ['name' => 'asc'],
    ]);

    echo "<pre>";
    echo "User found: " . print_r($users, true);
    echo "</pre>";

Example Usage: Using `include`

  use Lib\Prisma\Classes\Prisma;

    $prisma = Prisma::getInstance();
    $users = $prisma->user->findMany([
        'where' => ['email' => 'example@email.com'],
        'take' => 5,
        'include' => ['profile' => true]
    ]);

    echo "<pre>";
    echo "User found: " . print_r($users, true);
    echo "</pre>";

Example Usage: Advanced Filtering with String Matching

  use Lib\Prisma\Classes\Prisma;

    $prisma = Prisma::getInstance();
    $users = $prisma->user->findMany([
        'where' => ['name' => ['contains' => 'Doe']],
        'distinct' => true,
        'take' => 10,
        'skip' => 0,
        'orderBy' => ['name' => 'asc'],
    ]);

    echo "<pre>";
    echo "User found: " . print_r($users, true);
    echo "</pre>";

Example Usage: Using `select`

  use Lib\Prisma\Classes\Prisma;

    $prisma = Prisma::getInstance();
    $users = $prisma->user->findMany([
        'where' => ['name' => ['contains' => 'Doe']],
        'orderBy' => ['name' => 'asc'],
        'take' => 5,
        'select' => [
            'id' => true, 
            'name' => true, 
            'email' => true,
            'profile' => [
                'select' => [
                    'bio' => true
                ]
            ]
        ]
    ]);

    echo "<pre>";
    echo "User found: " . print_r($users, true);
    echo "</pre>";

Example Usage: Advanced Filtering Options

Illustrates how to use advanced filtering options such as contains, startsWith, endsWith, in, notIn, lt (less than), lte (less than or equal to), gt (greater than), gte (greater than or equal to), equals, and not for precise data querying.

  use Lib\Prisma\Classes\Prisma;

    $prisma = Prisma::getInstance();
    $users = $prisma->user->findMany([
        'where' => [
            'name' => [
                'contains' => 'Doe',
                'startsWith' => 'J',
                'endsWith' => 'e'
            ],
            'age' => [
                'gt' => 25,
                'lt' => 35
            ],
            'email' => [
                'in' => ['example1@email.com', 'example2@email.com'],
                'notIn' => ['admin@email.com']
            ],
            'status' => [
                'equals' => 'active',
                'not' => 'suspended'
            ]
        ],
        'orderBy' => ['name'], // Default is 'asc' unless specified, 'orderBy' => ['name' => 'desc']
        'take' => 10,
    ]);

    echo "<pre>";
    echo "Users found: " . print_r($users, true);
    echo "</pre>";

This example showcases filtering users by name patterns, age range, specific emails (including and excluding), and status, demonstrating the power of advanced filtering in data retrieval.

Understanding Logical Operators: AND, OR, NOT

Logical operators are powerful tools in constructing complex queries, allowing for the combination of multiple conditions. The where clause supports AND, OR, and NOT logical operators to refine search criteria.

AND

The AND operator allows for the combination of multiple conditions, all of which must be true for a record to match. It is useful for narrowing down results to those that meet all specified criteria.

OR

The OR operator matches records that fulfill at least one of the given conditions. It's ideal for expanding search results to include records that meet any of a set of criteria.

NOT

The NOT operator negates a condition, matching records that do not meet the specified criteria. It's used to exclude records from the results.

Example Usage

  use Lib\Prisma\Classes\Prisma;

    $prisma = Prisma::getInstance();
    $users = $prisma->user->findMany([
        'where' => [
            'OR' => [
                [
                    'email' => [
                        'contains' => 'gmail.com'
                    ]
                ],
                [
                    'AND' => [
                        [
                            'name' => [
                                'contains' => 'Reina'
                            ]
                        ],
                        [
                            'isActive' => true
                        ]
                    ]
                ]
            ],
            'NOT' => [
                'status' => [
                    'equals' => 'suspended'
                ]
            ]
        ]
    ]);

    echo "<pre>";
    echo "Users found: " . print_r($users, true);
    echo "</pre>";

This example showcases how to use AND, OR, and NOT logical operators to perform a complex query. It searches for users with an email containing "gmail.com" or users named "Reina" who are active, excluding those with a status of "suspended".