Add treat_numeric_as_conflict option to prevent ambiguous numeric slugs

[oehlschl]

Summary

We sometimes have issues where clients call our APIs and pass integer primary keys instead of slugs, but Model.friendly.find(id) finds a record with the same numeric slug, because our slug candidates are dynamic and in some cases purely numeric.

We'd like to prevent that, and so this PR adds a new configuration option treat_numeric_as_conflict prevent purely numeric slugs and therefore resolve the ambiguity where Model.friendly.find("123") could return either a record with slug="123" OR a record with id=123.

When enabled, purely numeric slug candidates are treated as conflicts and resolved using UUID suffixing, ensuring all slugs contain non-numeric characters that eliminate lookup ambiguity.

Changes

• Added treat_numeric_as_conflict configuration option to Slugged::Configuration
• Updated SlugGenerator to detect and reject purely numeric slugs when enabled
• Added purely_numeric_slug? helper method using Integer() validation (consistent with potential_primary_key?)
• Expanded test coverage for both default behavior and numeric prevention
• UPDATE: added Guide documentation and changelog entry

Usage

class Product < ApplicationRecord
  extend FriendlyId
  friendly_id :name, use: :slugged
  friendly_id_config.treat_numeric_as_conflict = true
end

# Results:
Product.create(name: "123")     # slug: "123-f9f3789a-daec-4156-af1d-fab81aa16ee5"
Product.create(name: "abc123")  # slug: "abc123" (unchanged)

Testing Done

• All existing tests pass
  • Verified backward compatibility (default behavior unchanged)
• Added comprehensive test coverage for new functionality
  • Tests cover edge cases: zero, large numbers, alphanumeric combinations
  • Verified UUID conflict resolution works for multiple numeric slugs

Deploy Notes

• No breaking changes: This is a new opt-in configuration option
• No migration required: Uses existing slug storage and UUID conflict resolution
• Safe to deploy: Feature is disabled by default, maintaining all existing behavior
• Rollback safe: Simply remove configuration option to disable

[oehlschl]

@parndt I know there's not a ton of active development on friendly_id now, but any concerns with something like this? Thanks in advance.

[parndt]

Thanks @oehlschl I think this seems fine to support. Is it possible to add to the changelog and add some docs around it for those using slugged so that people know it's an option (without reading the source code)?

[oehlschl]

Yes, will follow up with the additional changes tonight; thanks @parndt!

[oehlschl]

@parndt I added Guide documentation, and this change to the changelog (under Unreleased). Also updated the Int casting (will comment inline); please let me know if you need anything else. Thanks!

[oehlschl]

@parndt please let me know if you need anything else here, thanks!

[oehlschl]

Pardon the ping @parndt, but would you please cut a new release when you can? Thanks!

[parndt]

@oehlschl I will work on it; I've been meaning to set up trusted publishing for a while..

[parndt]

@oehlschl after much ado with rubygems publishing, we have version 5.6.0!

[fschwahn]

@oehlschl Thanks for this - we had some custom code to deal with this, which I can now drop!

[oehlschl]

Glad to hear it! Thanks all. Upgrading the gem and removing some of our own custom code now too.