Atualize a versão da biblioteca de integração Laravel

Versão 5.x: mudanças importantes

Esta versão da biblioteca introduz as seguintes alterações de quebra:

• O construtor de query retorna resultados como objetos stdClass em vez de arrays. Essa alteração exige que você altere o acesso da array ao acesso à propriedade ao interagir com os resultados da query.

  O código a seguir mostra como recuperar um resultado de query e acessar uma propriedade do objeto de resultado em versões mais antigas em comparação com a v5.0:

  $document = DB::table('accounts')    ->where('name', 'Anita Charles')    ->first();
  // older versions$document['balance'];
  // v5.0$document->balance;

• Remove o suporte para as seguintes classes:

  • MongoDB\Laravel\Auth\DatabaseTokenRepository. Em vez disso, use a classe Illuminate\Queue\Failed\DatabaseFailedJobProvider padrão e especifique uma conexão com o MongoDB.

  • MongoDB\Laravel\Queue\Failed\MongoFailedJobProvider. Em vez disso, use a classe Illuminate\Queue\Failed\DatabaseFailedJobProvider padrão e especifique uma conexão com o MongoDB.

• Ao usar um objeto DateTimeInterface , incluindo Carbon, em uma query, a biblioteca converte o DateTimeInterface em um objeto MongoDB\BSON\UTCDateTime . Essa conversão se aplica a objetos DateTimeInterface passados como filtros de query para o método where() ou como dados passados para os métodos insert() e update() .

  Para visualizar um exemplo que passa um objeto Carbon para o método DB::where() , consulte a seção Exemplo de correspondência de datas do guia Construtor de queries.

• Nos resultados da consulta, a biblioteca converte objetos BSON UTCDateTime em classes de data Carbon , aplicando o fuso horário padrão.

  No v5.1, a biblioteca também executa essa conversão para os resultados do método Model::raw() antes de ativar uma instância do modelo.

• id é um alias para o campo _id em documentos MongoDB e a biblioteca converte automaticamente entre id e _id ao executar query de dados. O objeto de resultado da query inclui um campo id para representar o campo _id do documento. Devido a esse comportamento, você não pode ter dois campos id e _id separados em seus documentos.

  No v5.1, a biblioteca também executa essa conversão para os resultados do método Model::raw() antes de ativar uma instância do modelo. Ao passar um filtro de query complexo, use o método DB::where() em vez de Model::raw().

  A partir de v5.3, você pode desabilitar a conversão automática de id para _id para documentos incorporados. Para saber mais, consulte a seção Desativar o uso da conversão de nome de campo ID do guia Opções de conexão.

• Remove o suporte para a propriedade $collection . O código a seguir mostra como atribuir uma coleção MongoDB a uma variável em sua classe User em versões mais antigas em comparação com a v5.0:

  use MongoDB\Laravel\Eloquent\Model;
  class User extends Model{    protected $keyType = 'string';
      // older versions    protected $collection = 'app_user';
      // v5.0    protected $table = 'app_user';
      ...}

  Esta versão também modifica os métodos DB e Schema associados para acessar uma collection do MongoDB . O código a seguir mostra como acessar a coleção app_user em versões mais antigas em comparação com a v5.0:

  use Illuminate\Support\Facades\Schema;use Illuminate\Support\Facades\DB;use MongoDB\Laravel\Schema\Blueprint;
  // older versionsSchema::collection('app_user', function (Blueprint $collection) { ... });DB::collection('app_user')->find($id);
  // v5.0Schema::table('app_user', function (Blueprint $table) { ... });DB::table('app_user')->find($id);

• A partir da v5.9, a versão mínima do Laravel é 12.0. Para obter instruções sobre como atualizar sua versão do Laravel, consulte o Guia de atualização na documentação do Laravel.

• A partir da v5.9, a versão mínima do PHP é 8.2. Antes de atualizar, confirme se o seu aplicativo é executado em uma versão compatível do PHP.

• A partir da v5.11, o método where() interpreta um valor de array como um valor literal nas seguintes condições:

  • Você passa 3 argumentos para o método where().

  • Um desses argumentos é o operador =.

  • Outro argumento é um valor de array.

  Em versões anteriores, a integração com o Laravel passava o array para o MongoDB como um documento de operador, o que poderia injetar condições de query não intencionais. Para aprender mais, consulte Valores de Array no guia do Query Construtor e o problema CVE-2026-88022. relacionado.

• A partir de v5.12, a configuração de conexão prefix se aplica aos métodos de esquema no construtor de esquemas da biblioteca, assim como no Laravel. Os métodos hasTable(), dropIfExists(), getColumns() e getIndexes() agora aplicam o prefixo ao nome da coleção que você passa. O mesmo se aplica a getColumnListing(), getIndexListing() e hasIndex(), que delegam para getColumns() e getIndexes(). Para saber mais sobre essa configuração, consulte Configuração de conexão do banco de dados Laravel.

  Se o seu aplicação passar um nome de coleção prefixado para esses métodos, passe o nome não prefixado. Por exemplo, se sua conexão usa um prefix de app_, chame Schema::hasTable('users') em vez de Schema::hasTable('app_users').

  hasCollection() e getCollection() não fazem parte da API de esquema do Laravel. Eles continuam a receber o nome da coleção conforme armazenado no MongoDB, para que os métodos possam usar um nome prefixado.

• Esta versão também corrige um problema de migração: antes de v5.12, php artisan migrate com um prefixo recria o repositório de migração em cada execução e executa todas as migrações novamente.

Alterações significativas na versão 4.x

Esta versão da biblioteca introduz as seguintes alterações de quebra:

• A versão mínima do Laravel agora é 10.0. Para obter instruções sobre como atualizar sua versão do Laravel, consulte o Guia de atualização na documentação do Laravel.

• O nome da dependência agora é "mongodb/laravel-mongodb". Certifique-se de que o nome da dependência em seu arquivo composer.json seja "mongodb/laravel-mongodb": "^4.0". Em seguida, execute composer update.

• O namespace agora é MongoDB\Laravel\. Certifique-se de alterar o namespace de Jenssegers\Mongodb\ para MongoDB\Laravel\ em seus modelos e arquivos de configuração.

• Remove o suporte para projetos que não sejam do Laravel.

• Remove o suporte para a propriedade $dates . Certifique-se de alterar todas as instâncias de $dates para $casts em seus arquivos de modelo.

• Model::unset($field) não persiste a alteração. Certifique-se de seguir todas as chamadas para Model::unset($field) com Model::save().

• Remove o método Query\Builder::whereAll($column, $values) . Certifique-se de substituir todas as chamadas para Query\Builder::whereAll($column, $values) por Query\Builder::where($column, 'all', $values).

• Query\Builder::delete() pode excluir um ou todos os documentos. Certifique-se de passar somente os valores 1 ou null para limit().

• whereDate(), whereDay(), whereMonth(), whereYear() e whereTime() métodos agora utilizam operadores MongoDB em campos de data.

• Adiciona o traço MongoDB\Laravel\Eloquent\MassPrunable . Certifique-se de substituir todas as instâncias de Illuminate\Database\Eloquent\MassPrunable por MongoDB\Laravel\Eloquent\MassPrunable em seus modelos.

• Remove o suporte para os seguintes métodos Query\Builder :

  • toSql()

  • toRawSql()

  • whereColumn()

  • whereFullText()

  • groupByRaw()

  • orderByRaw()

  • unionAll()

  • union()

  • having()

  • havingRaw()

  • havingBetween()

  • whereIntegerInRaw()

  • orWhereIntegerInRaw()

  • whereIntegerNotInRaw()

  • orWhereIntegerNotInRaw()

Versão 5.8 Itens obsoletos

A partir do Laravel MongoDB v5.8, o tipo de conversão array para atributos de modelo Eloquent está obsoleto. Usar array como um tipo de conversão armazena valores de atributos como strings codificadas em JSON no MongoDB, o que não é o formato BSON nativo. Quando você grava em um atributo que usa a conversão array, a biblioteca emite o seguinte aviso de obsolescência:

USER DEPRECATED  The "array" cast on attribute "<attribute>"of model "<Model>" stores values as a JSON-encoded string inMongoDB, which is not the native format. Remove the cast tostore native BSON arrays. If you must keep JSON stringstorage, use the "json" cast explicitly.

O aviso de descontinuação inclui o nome do atributo afetado e da classe de modelo.

Para migrar os atributos do seu modelo para versões futuras, use uma das seguintes opções:

• Remova o array cast (recomendado). Sem um tipo de cast, o MongoDB armazena e recupera nativamente arrays PHP como arrays BSON. O código a seguir mostra como atualizar seu modelo:

  // Before (deprecated in v5.8)protected $casts = [    'options' => 'array',];
  // After: remove the cast to use native BSON storageprotected $casts = [    // other casts...];

• Substitua array por json para manter explicitamente o armazenamento de string JSON:

  protected $casts = [    'options' => 'json',];

Se um campo já contiver um array BSON nativo e o modelo ainda usar a conversão array, a biblioteca o lerá corretamente.