docs: add getSlug() method and usage examples to API documentation

[vlados]

This PR adds the missing getSlug() method to the API documentation and includes practical usage examples for getting model URLs.

Changes:

• Added getSlug() method to API table with parameter descriptions
• Added "Getting Model URLs" section with code examples
• Documented usage of relative_url and absolute_url attributes

Closes #5

Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added getSlug() to the API reference with example usage.
  • Introduced a “Getting Model URLs” subsection showing how to retrieve relative and absolute URLs.
  • Included examples for language-specific URLs and default fallbacks.
  • Updated the API table to reflect the new entry and improve discoverability.
  • Documentation-only update; no functional or behavioral changes to the app.

[coderabbitai]

Walkthrough

README updated to document a new public method getSlug() and add a “Getting Model URLs” subsection with examples for relative/absolute URLs and language-specific/default behavior. Only documentation text and the API table were modified; no source code or exported entities changed.

Changes

Cohort / File(s)	Summary
Docs README.md	Added getSlug() entry to API/docs; introduced “Getting Model URLs” subsection with usage examples for relative/absolute URLs and language defaults; no code or logic changes.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title concisely describes the primary change by indicating that the getSlug() method and corresponding usage examples are being added to the API documentation, matching the content of the README updates. It avoids unnecessary information and follows conventional commit style with the “docs:” prefix, making the scope and intent immediately clear to reviewers.
Linked Issues Check	✅ Passed	The changes fully address issue #5 by updating the documentation to include the getSlug() method in the API table and adding examples for obtaining model URLs using both relative_url and absolute_url attributes, fulfilling the requirement to document methods and attributes for generating model URLs. The PR description confirms that all linked objectives from issue #5 have been implemented in the README without missing any specified items.
Out of Scope Changes Check	✅ Passed	All modifications are confined to the README documentation, specifically enhancing the API section with the getSlug() method and usage examples, and no unrelated code or files have been altered, confirming that there are no out-of-scope changes.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/issue-5-20251001-2037

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Code Review

Thanks for adding this documentation! This is a helpful addition that closes #5. Overall, the PR looks good with clear examples. Here are a few observations and suggestions:

✅ Strengths

• Clear examples: The usage examples are practical and cover common use cases
• Accurate documentation: Verified against HasUniqueUrlAttributes.php:32 - the method signature and behavior match the documentation
• Good placement: The new "Getting Model URLs" section logically follows the API table
• Consistency: Follows the existing documentation style

🐛 Issues Found

1. Incorrect parameter description in API table (line 172)

The parameter documentation shows:

?string $language = '', bool $relative = true

However, the actual method signature in src/HasUniqueUrlAttributes.php:32 is:

public function getSlug(?string $language = '', bool $relative = true): string|null

The default value for $language is an empty string '', not null. When an empty string is passed, the method defaults to app()->getLocale(). This is a minor inconsistency but worth noting for accuracy.

Suggested fix:

| getSlug() | Get the URL for a specific language in relative or absolute format | ?string $language = null, bool $relative = true |

And update the implementation to use null as default instead of '' for clarity, OR keep the docs as-is but clarify that empty string defaults to app locale.

💡 Suggestions for Improvement

1. Add null return value to examples

The method can return null if no URL exists for the language. Consider adding an example:

// Returns null if no URL exists for the language
$url = $model->getSlug('fr'); // null if French URL not generated

2. Clarify the difference between empty string and null

From the code (HasUniqueUrlAttributes.php:34):

$language = $language ? $language : app()->getLocale();

Both null and '' (empty string) default to app locale. The docs could clarify this behavior.

3. Minor: Parameter description accuracy

In the table, consider being more specific:

| getSlug() | Get the URL for a specific language in relative or absolute format | string $language (defaults to app locale), bool $relative = true |

✨ Test Coverage

Good news: Existing tests already verify this functionality (see tests/HasUniqueUrlsTest.php:21,27,35,40,86), so the documented behavior is well-tested.

📝 Summary

This is a solid documentation PR that adds value to the project. The only issue is a minor inconsistency in the parameter default value. Consider clarifying the null return case for completeness.

Recommendation: Approve with minor suggestions ✅

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3632034 and 4ae846e.

📒 Files selected for processing (1)

• README.md (2 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

README.md

172-172: Hard tabs
Column: 35

(MD010, no-hard-tabs)

🔇 Additional comments (1)

README.md (1)

182-199: Examples read clearly.

The new “Getting Model URLs” section spells out the common cases succinctly—thanks for adding it.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Replace the hard tab with spaces to satisfy markdownlint.

Line 172 still contains a tab character (MD010). Swap the tab for spaces so the docs pass lint.

-| getSlug()                       	 | Get the URL for a specific language in relative or absolute format | ?string $language = '', bool $relative = true |
+| getSlug()                         | Get the URL for a specific language in relative or absolute format | ?string $language = '', bool $relative = true |

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	| getSlug() | Get the URL for a specific language in relative or absolute format | ?string $language = '', bool $relative = true |
	| urlStrategy | The strategy for creating the URL for the model | $language, $locale |
	| getSlug() | Get the URL for a specific language in relative or absolute format | ?string $language = '', bool $relative = true |
	| urlStrategy | The strategy for creating the URL for the model | $language, $locale |

🧰 Tools

🪛 markdownlint-cli2 (0.18.1)

172-172: Hard tabs
Column: 35

(MD010, no-hard-tabs)

---

173-173: Hard tabs
Column: 35

(MD010, no-hard-tabs)

---

173-173: Hard tabs
Column: 99

(MD010, no-hard-tabs)

---

173-173: Hard tabs
Column: 121

(MD010, no-hard-tabs)

🤖 Prompt for AI Agents

In README.md around lines 172 to 173, there is a hard tab character in the table
row for "urlStrategy" causing markdownlint MD010; replace the tab with
equivalent spaces so the table columns align using spaces (e.g., convert the
single tab between columns to two or more spaces to match surrounding rows),
save the file, and re-run the linter to confirm the MD010 warning is resolved.