Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allowing table inspection to gracefully fail so other IDE helpers for models may still be generated #1528

Open
wants to merge 5 commits into
base: master
Choose a base branch
from

Conversation

clayzar
Copy link

@clayzar clayzar commented Feb 22, 2024

Summary

This adds logic to allow table inspection to gracefully fail. More specifically, this allows other the doc block generation to continue and generate other helpers that aren't database related.

A use case for this is for NoSQL database drivers, for which schema inspection doesn't make sense or doesn't have a convention to determine columns, yet is still helpful to have a handful of the other IDE helpers that this package is capable of generating. Currently, when using the latest Laravel MongoDB package the corresponding driver does not implement the compileColumns method. So we see an error thrown that mentions this undefined method when running the command to generate doc blocks for models configured to use a Mongo DB connection.

I've linked a couple of issues that mention this.

I've also added silence-able warnings if table properties could not be inspected for a given model. A warning is output as the command generates output and another at the end of the output denoting the models whose table could not be inspected, to ensure the developer is aware to scroll up should the output be many lines long.

#590
mongodb/laravel-mongodb#1785

Type of change

This could be thought of as a bug fix, new feature, or misc change – depending on how you look at it.

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update
  • Misc. change (internal, infrastructure, maintenance, etc.)

Checklist

  • Existing tests have been adapted and/or new tests have been added
  • Add a CHANGELOG.md entry
  • Update the README.md
  • Code style has been fixed via composer fix-style

Copy link
Collaborator

@mfn mfn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general I can see the value, but I don't think we should change the default behaviour.

With that I mean and based on my understanding how the PR works from reading the code:

It now collects all those errors. If there an error not related to your scenario, like a complete failure of proper setup, in the current version we swallow the exception completely and leave the user in the dark, but tell them all the n models failed. That's not helpful.

Before that, it stopped on the first error, gives a the full stacktrace, and allows the user assess the situation.

I think this whole behaviour should be able to disabled and by default the exception should be thrown.

My suggestion for the approach would be:

  • default value for ide-helper.silenced_models of null is the current behaviour
  • only if it is an array (empty or not), it will perform your sanity checks.

WDYT?

config/ide-helper.php Show resolved Hide resolved
$connectionName = $model->getConnectionName() ?? $this->laravel['config']->get('database.default');
$driver = $model->getConnection()::class;

$this->warn("Could not get table properties for model [{$modelName}] using connection [{$connectionName}]. The underlying database driver [{$driver}] may not be supported.");
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although this is already a long text, we should not swallow that actual content of $e, I suggest something like appending: … be supported: " . get_class($e) . ' ' . $e->getMessage()

@clayzar
Copy link
Author

clayzar commented Feb 23, 2024

Great thoughts here! I've made those adjustments and also tucked away the updates more neatly. Just to regurgitate what you had in mind:

If the ide-helpers.silenced_models value is null or otherwise missing (such would be the case for current projects using the package).. no behavior changes, the exception will be thrown if it fails.

Otherwise, this will gracefully handle an exception when inspecting the table and provide warnings in the output. Those warnings can be silenced by specifying the FQCN of the class in ide-helper.silenced_models.

I've added the exception class and message to the output. Here's a sample of the output in an example project with 2 models that use a MongoDB connection

Screenshot 2024-02-23 at 4 52 32 PM

Copy link
Collaborator

@mfn mfn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You fail to account for that when you perform a new installation and the ide config is copied over, the value is not null but an empty array: the BC compatibility I was talking about extends to the behaviour in general:

  • disabled by default
  • enabled deliberately

I also feel the additional changes go overboard and I see no need to:

  • write a warning when the model happens
  • collect everything
  • again write out a warning and only this time the error

The footprint of the PR for the functionality required will be much smaller in scope and easier to reason (throw out the enum, don't collect the warnings, spit out the error immediately; the encapsulation in methods is 👌🏼 )

If you agree to the changes, feel free to go ahead and also add appropriate tests and an entry to the CHANGELOG, overall the idea is 👍🏼

@clayzar
Copy link
Author

clayzar commented Feb 27, 2024

I feel that setting the value of silenced_models to an empty array to allow graceful error handling isn't very intuitive.

With the warning collection, I was trying to map out something that could be used in case other warnings were ever possible, but I realize this may be a little overblown for the need here.

Thinking back on the primary goal here, I think it may be simpler to just use a config setting named skip_model_tables that defaults to an empty array. This would default to the same behavior as today (disabled) and must be enabled deliberately. The items in the array would be FQCN for any model for which table inspection should be skipped. The value could also be set to * to skip all models without having to explicitly list each one, helpful for large code-bases exclusively using an unsupported database driver.

Thoughts?

@mfn
Copy link
Collaborator

mfn commented Mar 4, 2024

Thoughts?

Let's see code and I suggest you make (another) PR to discuss this!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants